Gambas Documentation
Application Repository
Code Snippets
Compilation & Installation
Components
gb
gb.args
gb.cairo
gb.chart
gb.clipper
gb.complex
gb.compress
gb.crypt
gb.data
gb.db
gb.db.form
gb.db.mysql
gb.db.odbc
gb.db.postgresql
gb.db.sqlite2
gb.db.sqlite3
gb.dbus
gb.dbus.trayicon
gb.debug
gb.desktop
gb.desktop.gnome.keyring
gb.desktop.x11
gb.eval
gb.eval.highlight
gb.form
gb.form.dialog
gb.form.editor
gb.form.htmlview
gb.form.mdi
gb.form.print
gb.form.stock
gb.form.terminal
gb.gmp
gb.gsl
gb.gtk
gb.gtk.opengl
gb.gtk3
gb.gtk3.opengl
gb.gtk3.webview
gb.gui
gb.gui.opengl
gb.gui.qt
gb.gui.qt.ext
gb.gui.qt.opengl
gb.gui.qt.webkit
gb.gui.trayicon
gb.gui.webview
gb.hash
gb.highlight
gb.image
gb.image.effect
gb.image.imlib
gb.image.io
gb.inotify
gb.jit
gb.libxml
gb.logging
gb.map
gb.markdown
gb.media
gb.media.form
gb.memcached
gb.mime
gb.mongodb
gb.mysql
gb.ncurses
gb.net
gb.net.curl
gb.net.pop3
gb.net.smtp
gb.openal
gb.opengl
gb.opengl.glsl
gb.opengl.glu
gb.opengl.sge
gb.openssl
gb.option
gb.pcre
gb.pdf
gb.poppler
gb.qt4
.combobox.item
.container.children
.Menu.Children
.TabStripContainer
.TabStripContainer.Children
.TextArea.Selection
.TextBox.Selection
.Window.Controls
.Window.Menus
_ColumnView_Columns
_ComboBox_Item
_ComboBox_Selection
_Draw_Clip
_Draw_Style
_GridView_Cell
_GridView_Column
_GridView_Columns
_GridView_Data
_GridView_Row
_GridView_Rows
_Gui
_IconView_Item
_ListBox_Item
_split
_TreeView
_TreeView_Item
Action
Align
Animation
Application
Arrange
Border
Button
CheckBox
Clipboard
Color
ColumnView
ComboBox
Container
ContainerChildren
Control
Cursor
Desktop
Dialog
Direction
Drag
Draw
DrawingArea
embedder
Fill
Font
Fonts
Form
_new
Load
Main
Frame
GridView
HBox
HPanel
HSplit
IconView
Image
Key
Label
Line
ListBox
ListView
Menu
Message
Mouse
MovieBox
Paint
PaintBrush
PaintExtents
PaintMatrix
Panel
Picture
PictureBox
Point
Pointer
PointF
Printer
ProgressBar
RadioButton
Rect
RectF
Screen
Screens
Scroll
ScrollArea
ScrollBar
ScrollView
Select
Separator
Slider
SpinBox
Splitter
Spring
Style
SvgImage
TabStrip
TextArea
TextBox
TextLabel
ToggleButton
ToolButton
trayicon
trayicons
TreeView
UserContainer
UserControl
VBox
VPanel
VSplit
Watcher
Window
Windows
gb.qt4.ext
gb.qt4.opengl
gb.qt4.webkit
gb.qt4.webview
gb.qt5
gb.qt5.ext
gb.qt5.opengl
gb.qt5.webkit
gb.qt5.webview
gb.qt6
gb.qt6.ext
gb.qt6.opengl
gb.qt6.webview
gb.report
gb.report2
gb.scanner
gb.sdl
gb.sdl.sound
gb.sdl2
gb.sdl2.audio
gb.settings
gb.signal
gb.term
gb.test
gb.util
gb.util.web
gb.v4l
gb.vb
gb.web
gb.web.feed
gb.web.form
gb.web.gui
gb.xml
gb.xml.html
gb.xml.rpc
gb.xml.xslt
Controls pictures
Deprecated components
Developer Documentation
Development Environment Documentation
Documents
Error Messages
Gambas Playground
How To's
Language Index
Language Overviews
Last Changes
Lexicon
README
Search the wiki
To Do
Topics
Tutorials
Wiki License
Wiki Manual

Form (gb.qt4)

The parent class of every form of a program.

This class inherits Window.

This class can be used like an object by creating a hidden instance on demand.

This class is creatable.

This class acts like a read-only array.

Inherited constants
Above   This constants is used by the Stacking property for windows that must stay above other windows.
Below   This constants is used by the Stacking property for windows that must stay below other windows.
Normal   This constants is used by the Stacking property for windows that have a normal stacking order.

Static methods
Load   Creates the hidden default instance of the form.
Main   This method allows the Development Environment to use forms as startup classes.

Inherited properties
Action   Returns or sets the action string associated with the control.
Arrangement   Returns or sets how this container arrange its children controls.
AutoResize   Returns or sets if the window will automatically resize to fit its contents.
Background   Returns or sets the background color used by the control.
Border   Return or set if the window has a border.
Caption   A synonymous for the Text property.
Centered   Center controls horizontally or vertically according to the container arrangement.
Children   Returns a collection of each control included in the container.
ClientH   A synonymous for the ClientHeight property.
ClientHeight   Returns the height of the area containing the controls.
ClientW   A synonymous for the ClientWidth property.
ClientWidth   Returns the width of the area containing the controls.
ClientX   Returns the position of the left border of the area containing the controls.
ClientY   Returns the position of the top border of the area containing the controls.
Closed   Returns if the window has been closed.
Controls   Returns a collection of all controls that belong to this window.
Cursor   Use this property for assigning a custom cursor to a control.
Design   Indicates that the control is in design mode.
Direction   Return or set the control text direction.
Drop   Returns or sets if a control accepts drops.
Enabled   Indicates that the control is enabled.
Expand   Returns or sets if a control will expand if included in a container that arranges its contents.
Font   Returns or sets the font used to draw text in the control.
Foreground   Returns or sets the foreground color used by the control.
FullScreen   Returns or sets if the window is shown in fullscreen mode.
Geometry   Return the last geometry of the window when it was in normal state.
H   A synonymous for the Height property.
Handle   Returns the internal X11 window handle of the control.
HasFocus   Returns whether the control has the focus.
Height   Returns or sets the height of the control.
Hovered   Returns whether the mouse cursor is inside the control.
Icon   Returns or sets the picture used as an icon by the window.
Id   A synonymous for the Handle property.
Ignore   Returns or sets if a control must be ignored when its parent arranges its children.
Indent   Returns or sets if the children controls of the container are indented.
Invert   Return or set if the horizontal or vertical arrangement direction is inverted.
Left   Returns or sets the position of the left border of the control relative to its parent.
Margin   Returns or sets if there is a margin between the container border and all its children.
Mask   Returns or sets if Picture must be used as a shape mask by the window.
Maximized   Returns or sets if the window is maximized.
Menus   Returns a collection of all menus of the window menu bar.
MinH   Return or set the minimum height of the window.
MinHeight   Return or set the minimum height of the window.
MinW   Return or set the minimum width of the window.
MinWidth   Return or set the minimum width of the window.
Minimized   Returns or sets if the window is minimized.
Modal   Returns if a window is currently displayed modal.
Mouse   Returns or sets the appearence of the cursor when it points inside the control.
Name   Returns or sets the name of the control.
Next   Returns the next control having the same parent.
NoTabFocus   Return or set if a control cannot be focused with the TAB key.
Opacity   Return or set the of the window.
Padding   Returns or sets the number of pixels used as space between children controls, or container inner margin.
Parent   Returns the control container.
Persistent   Indicates if the window is persistent, i.e. if it is not destroyed but only hidden when the users closes it.
Picture   Returns the picture displayed in the window background.
PopupMenu   Return or set the name of the menu that will be popped-up when the user presses the right mouse button or the keyboard MENU key.
Previous   Returns the previous control having the same parent.
Proxy   Return or set the "proxy" of a control.
ProxyFor   Return which control that control is a proxy for.
Resizable   Constant used by the Border property to indicate that the window is freely resizable.
RightToLeft   Return if the control is right to left oriented.
Screen   Return the monitor index where the window is located.
ScreenX   Returns the position of the left border of the control in screen coordinates.
ScreenY   Returns the position of the top border of the control in screen coordinates.
SkipTaskbar   Indicates if the window is displayed or not in the desktop task bar.
Spacing   Returns or sets if the children of the container are spaced out.
Stacking   Returns or sets the stacking group of the window.
Sticky   Returns or sets if the window is visible in all virtual desktops.
Tag   Returns or sets the control tag.
TakeFocus   Return or set if the window takes the focus automatically when it is opened.
Text   Returns or sets the title of the window.
Title   A synonymous for the Text property.
Tooltip   Returns or sets the tooltip shown when the mouse stays on the control for a short time.
Top   Returns or sets the position of the top border of the control relative to its parent.
TopLevel   Returns if a window is a top-level window.
TopOnly   Returns or sets if a window stays on top on all other windows.
Tracking   Returns or sets if the control will receive MouseMove events.
Transparent   Return or set if the window background is transparent, i.e. if it takes the alpha components of its background color or picture into account.
Utility   Return or set if the window is an utility window, as defined by the freedesktop standard.
Visible   Returns or sets if a window is visible.
W   A synonymous for the Width property.
Width   Returns or sets the width of the control.
Window   Returns the top-level window that contains the control.
X   Returns or sets the position of the left border of the control relative to its parent.
Y   Returns or sets the position of the top border of the control relative to its parent.

Inherited methods
Activate   Activates the window.
Center   Centers the window on screen.
Close   Closes the window, and returns an optional integer value used by the
Delete   Deletes the window.
Drag   Starts a drag & drop process.
FindChild   Finds the first child control pointed by the X and Y coordinates.
Grab   Grab the keyboard and the mouse so that all keyboard and mouse events are received by the control.
Hide   Hides the control.
Lower   Sends the control to the background of its parent.
Move   Moves and/or resizes the control.
MoveScaled   Moves and/or resizes the control.
Raise   Raises the window.
Refresh   Trigger a redraw of the control.
Reparent   Changes the container of a control.
Resize   Resizes the control.
ResizeScaled   Resizes the control.
SetFocus   Gives the focus to the control.
Show   Shows the window in non-modal mode.
ShowDialog   A synonymous for the ShowModal method.
ShowModal   Shows the window in modal mode.
ShowPopup   Use that window to display a popup.

Inherited events
Activate   Raised when the window is activated.
Arrange   This event is raised when a container has just finished arranging its contents.
BeforeArrange   This event is raised just before a container arranges its contents.
Close   Raised when the window is going to be closed.
DblClick   Raised when the user quickly clicks twice on the control.
Deactivate   Raised when the window is deactivated.
Drag   This event is raised when the mouse enters the control during a drag & drop process.
DragLeave   This event is raised when the mouse leaves the control during a drag & drop operation.
DragMove   This event is raised while the mouse moves inside the control during a drag & drop process.
Drop   This event is raised when a drag is dropped in the control.
Enter   Raised when the mouse enters the control.
Font   This event is raised when the window font changes.
GotFocus   Raised when the control has got the focus.
Hide   Raised when the window is hidden.
Icon   This event is raised when the window icon changes.
KeyPress   Raised when a key is pressed while the control has the focus.
KeyRelease   Raised when a key is released while the control has the focus.
Leave   Raised when the mouse leaves the control.
LostFocus   Raised when the control has lost the focus.
Menu   Raised when the user clicks on the control with the right mouse button, or if it hits the MENU key.
MouseDown   Raised when a mouse button is pressed while the cursor is inside the control.
MouseDrag   This event is raised when a drag operation should be started.
MouseMove   Raised when the mouse moves inside the control while a mouse button is pressed.
MouseUp   Raised when a mouse button is depressed while the cursor is inside the control.
MouseWheel   This event is raised when the user moves or presses the mouse wheel while the mouse is inside the control.
Move   Raised when the window is moved.
NewChild   This event is raised when a new child Control has just been inserted into the container.
Open   Raised when the window is going to be visible for the first time.
Resize   Raised when the window is resized.
Show   Raised when the window is shown.
State   This event is raised when the Minimized, Maximized or FullScreen property changes.
Title   This event is raised when the window title changes.

Event management

By default, a form is its own event observer.

It means that all the events raised by the Form object are caught by event handlers defined in the form source code.

Automatic instance

Forms internally manages an automatic singleton instance.

It means that you can use the form class name as a form instance. The first time you do that, the internal singleton is automatically created.

You can force the creation of the automatic instance by using the Load method.

Startup form

A form can be the startup class of the project, as it implements a Main method. In that case, the automatic instance of the form is used.

Examples


' Instanciate the automatic instance, move it and show it

MyForm.Move(90, 150)
MyForm.Title = "Automatic instance"
MyForm.Show

' Do the same thing with another instance of the same form

Dim hForm As MyForm

hForm = New MyForm
hForm.Title = "Another instance"
hForm.Move(110, 170)
hForm.Show

...

' Event handler in the MyForm source code

Public Sub Form_Open()

  Print "Showing form: "; Me.Title

End

Warning about wayland...

There are some serious issues with wayland that you should be aware of with regards to positioning a "Top level" form.
For a standard GUI (open and close) application this may not present a problem but for a desktop background GUI with no border you may find issues if some kind of custom positioning is required.

It is currently NOT possible to position the main form by code on a wayland system.

wayland is in full control of form positioning and we can do nothing about it with code.

A Form with a border/titlebar can be moved as expected with a mouse click on the titlebar but you cannot move a form without a titlebar using code.

You also cannot save/restore From positions using Settings.Read() Setting.Write()

Form_Move() event will also not trigger. (except when the form opens)
Getting or Setting Form.X and Form.Y will not work. The X and Y values are not to the parent screen as wayland considers the applications main window to be the "top level" not the Screen so it's screen position cannot be determined.

Using Form.Move(X, Y) command will also not work.