User Tools

Site Tools


12.3.3 Action

The two classes Action (gb.qt4) and Action (gb.form.mdi) allow you to manage the actions that you can define in the Action property of many components. The Action (gb.qt4) class behaves like a ReadOnly array. With the help of the Action (gb.qt4) class, you can then synchronously access all these controls thus distinguished. The following components have the 'Action' property:

Button, ButtonBox, CheckBox, ColorButton, ColorChooser, ColumnView, ComboBox, Container, Control, DateBox, DateChooser, Dial, DirChooser, DirView, Drag, DrawingArea, Editor, Embedder, Expander, FMain, FileChooser, FileProperties, FileView, FontChooser, Form, Frame, GridView, HBox, HPanel, HSplit, IconPanel, IconView, ImageView, LCDLabel, LCDNumber, Label, ListBox, ListContainer, ListView, MaskBox, Menu, MenuButton, MovieBox, Panel, PictureBox, ProgressBar, RadioButton, ScrollArea, ScrollBar, ScrollView, Separator, SidePanel, Slider, SliderBox, SpinBox, TabPanel, TabStrip, TableView, TextArea, TextBox, TextEdit, TextLabel, ToggleButton, ToolButton, ToolPanel, TreeView, UserContainer, UserControl, VBox, VPanel, VSplit, ValueBox, Window, Wizard, _IconPanelContainer, _Split, _TabPanelContainer, _TreeView, _WizardContainer.


A ToolButtonS (on a toolbar) and a menu item are both intended to save a file. Both components would therefore be assigned as an action string in the IDE, for example “SaveFile”, in order to synchronise their actions. Only if the opened file was modified, then the save function should be activated, which was switched off for both components when the file was opened. Both the corresponding ToolButtonS and the associated menu item are still visible - but greyed out! Here are the two matching source code excerpts:

Action["SaveFile"].Enabled = False 	' Save for ToolButton and deactivate menu item
Action["SaveFile"].Enabled = True 	' Save for ToolButton and activate menu item

It has proven advantageous to assign the Action property to the corresponding components and menu items directly in the IDE, because you can only call up both the dialogue for defining ShortCuts by the user and read out the list of all actions if you use the Action class (gb.form.mdi). If you want to do without this, then define the actions for selected components in the source code as follows as an example:

mnu12SaveFile.Action = "SaveFile"
toolbSaveFile.Action = "SaveFile"

In the hidden project folder .action is the Gambas action file formularname.action, which contains, for example, information about the name of the action (action string), the text to be displayed or the set ShortCut:

# Gambas Action File 3.0

{ Actions
  { Action SaveFile
    Text = "Save"
    Shortcut = "CTRL+S"
    Picture = "icon:/16/save"
  { Action HelpMe
    Text = "Program help"
    Shortcut = "F1"
    Picture = "icon:/16/help"
} Properties of the Action (gb.qt4) class

The properties of the Action (gb.qt4) class are given in the following table:

ActionData typeDefaultDescription
ControlsObject[]-Returns a list of all associated components that are linked to the defined action.
EnabledBooleanTrueEnables or disables all components associated with the action.
PicturePictureZeroDetermines or sets which icon is displayed in all components associated with the action.
ShortcutStringZeroDetermines or sets which keyboard shortcut is assigned to all components associated with the action.
TextStringZeroDetermines or sets which text is displayed for all components associated with the action.
ToolTipStringZeroDetermines or sets which ToolTip is displayed for all components associated with the action.
VisibleBooleanTrueHides or shows all components associated with the action.
ValueBooleanTrueDetermines or sets the Toogle value for all components associated with the action.

Table Action Properties (gb.qt4)

Please note that you can only set the properties that exist for all associated components.

mnu15Print.Action = "PrintImage"
toolbPrintImage.Action = "PrintImage"
Action["PrintImage"].ToolTip = "Print image file"

The last statement, for example, generates an error and the error message also gives the reason: Unknown symbol 'ToolTip' in class 'Menu' in FMain:31; property does not exist in class Menu.

The effect of the Action.Value property depends on the component in question:

  • If the component is a true toggle control such as a ToggleButton or a ToolButton with the Toggle property set, its Toogle value is set or not set.
  • However, if it is a SidePanel, a toolbar or a window, for example, then the Visible property is set against it. The Action_Activate event handler

To know when an action is triggered, you must define the event handler “Action_Activate” in the form. This event handler takes a string as an argument that denotes the action that is triggered.

Public Sub Action_Activate(sActionString As String) As Boolean
  Select Case sActionString
    Case "ImageOpen"
    Case "HelpMe"
    Case "PrintFile"
       ' Procedure for printing the edited file
    Case "FormClose"
  End Select ' sActionString
End ' Action_Activate(..) Properties and methods Class Action (gb.form.mdi)

The Action (gb.form.mdi) class has only one property and one method:

  • The class has the property List (data type Array), whose value you can only read. In the list, all found actions are listed in order.
  • Calling the Configure method starts a dialogue in which the user can define his own ShortCuts, which immediately apply project-wide and overwrite existing settings. Project

In many programmes it is possible to extend the interactive user guidance via a menu bar by a toolbar. The toolbar provides DeepL access to the most important sub-programs of the application programme.

The use of a toolbar next to a menu is based on the idea that the selection of a certain menu item causes the same (partial) programme call as a mouse click on the corresponding tool button. The linking of individual menus and their function with the selected tool button is of decisive importance for the desired effect. In the project, the Action class is used for synchronisation between the menu and the associated ToolButton on a toolbar. For the project with the very manageable menu bar and the few ToolButtons in the toolbar, this is not absolutely necessary, but it focuses all programme calls triggered by the menu and ToolButton in one procedure! This is an advantage you will appreciate if you want to use a menu bar with many menus and submenus and a toolbar in an extensive menu structure.

To implement the idea, it is useful to enter all menus and (tool) buttons in a table, define suitable identifiers and specify the associated components:

Image file mnuMenu1
Open…mnu11OpenImage OpenImagetbOpen
Printmnu13PrintImage PrintImagetbPrint
Closemnu14CloseForm CloseFormtbCloseForm
Configuration mnuMenu2
Action configurationmnu21ConfigAction ConfigActiontbConfigAction
Help mnuMenu3
Programme Helpmnu31Help HelpMetbHelpMe
Help on the Internetmnu32HelpNetinternetF12

Table Entries in the menu editor (S → Synchronisation, FT → Function key)

In the project presented, the menu - as a compilation of many menus - is created and configured with the menu editor according to the specifications in Table

Illustration Menu Editor (detail)

For 5 menus, the appropriate action string from table is entered under the 'Action' property and the qualified values for the 'Visible' and 'Enabled' properties are set.For the 5 associated components (ToolButton), the action strings from table are also entered in the IDE at development time. It is only important that the identifiers for the action property for the associated menus and ToolButton are the same!

The ToolBar component is used as a container for the horizontal toolbar in which 6 ToolButtons are placed next to each other. At development time, the 5 associated components are assigned the same icons (16px) from the Gambas inventory (so that the ToolButton can be recognised) and the menus in the editor none! Apart from the height (32px) and a width of the toolbar that matches the form, no other properties are changed. The arrangement of the 5/6 tool buttons is done automatically at runtime with a fixed distance to each other:

Figure Menu and toolbar

The source code is given in full and commented on in essential parts:

[1]   ' Gambas class file
[3] Public Sub Form_Open()
[5]   FMain.Center
[6]   FMain.Resizable = False
[8]   FMain.Text = "Synchronisation menu and toolbar"
[9]   PictureBox1.Border = Border.Sunken
[10]   PictureBox1.Picture = Picture["blume.jpg"]
[11]   lblPictureFileName.Text = "Flowers in Allgäu - Eyebright"
[13]   Action["OpenImage"].Enabled = True
[14]   Action["OpenImage"].Picture = Picture["icon:/16/open"]
[15]   Action["OpenImage"].Shortcut = "Ctrl+O"
[16]   Action["OpenImage"].Visible = True
[18]   Action["PrintImage"].Enabled = True
[19]   Action["PrintImage"].Picture = Picture["icon:/16/print"]
[20]   Action["PrintImage"].Shortcut = "Ctrl+P"
[21]   Action["PrintImage"].Visible = False ' (!)
[23]   Action["CloseForm"].Enabled = True
[24]   Action["CloseForm"].Picture = Picture["icon:/16/quit"]
[25]   Action["CloseForm"].Shortcut = "Ctrl+Q"
[26]   Action["CloseForm"].Visible = True
[27]   Action["CloseForm"].Text = " End"
[29]   Action["ConfigAction"].Enabled = True
[30]   Action["ConfigAction"].Picture = Picture["icon:/16/access"]
[31]   Action["ConfigAction"].Shortcut = "F6"
[32]   Action["ConfigAction"].Visible = True
[34]   Action["HelpMe"].Enabled = True
[35]   Action["HelpMe"].Picture = Picture["icon:/16/help"]
[36]   Action["HelpMe"].Shortcut = "F1"
[37]   Action["HelpMe"].Visible = True
[39]   tbSyncList.Tooltip = "List of" & gb.NewLine & "Synchronised components"
[41] End ' Form_Open()
[43] Public Sub Action_Activate(sActionString As String) As Boolean
[45]   Select Case sActionString
[46]     Case "OpenImage"
[47]       OpenImage
[48]     Case "PrintImage"
[49]       PrintImage
[50]       Action["PrintImage"].Enabled = False
[51]     Case "CloseForm"
[52]       Form_Close()
[53]     Case "ConfigAction"
[54]       Action.Configure
[55]     Case "HelpMe"
[56]       FHelp.Show
[57]   End Select ' sActionString
[59] End ' Action_Activate(..)
[61] Public Sub OpenImage()
[63]   Dialog.Title = "Import an image file!"
[64]   Dialog.Filter = ["*.png", "Image file"]
[66]   If Dialog.OpenFile(False) = True Then ' Multiselect=False (Standard)
[67]      Message.Info("The opening of the image file was cancelled!")
[68] Return ' Cancel button pressed
[69] Else
[70] Try PictureBox1.Picture = Picture.Load(Dialog.Path)
[71] If Error Then
[72] Message.Error("Error opening the picture file.")
[73]        Return
[74]     Else
[75]        lblPictureFileName.Alignment = Align.Left
[76]        lblPictureFileName.Text = "File name: " & File.Name(Dialog.Path)
[77]        Action["PrintImage"].Visible = True
[78]        Action["PrintImage"].Enabled = True
[79]     Endif ' ERROR ?
[80]   Endif ' Dialog.OpenFile ?
[82] End ' OpenImage()
[84] Public Sub PrintImage()
[85]   Message.Info("Insert print routine here!\nThe image is printed.")
[86] End ' PrintImage()
[88] ' Note: The menu name is also the identifier for the event handler.
[89] Public Sub mnu32HelpNet_Click()
[90]   Desktop.Open("")
[91] End ' mnu32HelpNet_Click()
[93] Public Sub mnu22ListAction_Click()
[94]   Dim iCount As Integer
[95]   Dim sMessage, sTrennLinie, sSpace, sSpace2 As String
[97]   sTrennLinie = "-----------------------"
[98]   sSpace = "   »   "
[99]   sSpace2 = "   *   "
[100]   sMessage = sTrennLinie & sTrennLinie & gb.NewLine
[101]   sMessage &= "Liste aller Action-Strings" & gb.NewLine
[102]   sMessage &= sTrennLinie & sTrennLinie & gb.NewLine & gb.NewLine
[104]   For iCount = 1 To Action.List.Count
[105]     If Action.List[iCount - 1] Like "[A-Z]*" Then
[106]        sMessage &= iCount & sSpace & Action.List[iCount - 1] & gb.NewLine
[107]     Else
[108]        sMessage &= iCount & sspace2 & Action.List[iCount - 1] & gb.NewLine
[109]     Endif ' Action.List[iCount - 1] Like "[A-Z]*" ?
[110]   Next ' iCount
[112] Message.Title =
[113]   Message.Info(sMessage)
[115] End ' mnu22ListAction_Click()
[117] Public Sub tbSyncList_Click()
[118]   Dim iCount, k As Integer = 1
[119]   Dim sActionString, sMessage, sTrennLinie, sSpace As String
[121]   sTrennLinie = "--------------------------------"
[122]   sSpace = "              » "
[123]   sMessage = sTrennLinie & sTrennLinie & gb.NewLine
[124]   sMessage &= "List of synchronised components" & gb.NewLine
[125]   sMessage &= sTrennLinie & sTrennLinie & gb.NewLine & gb.NewLine
[127]   For Each sActionString In Action.List
[128]     If Action[sActionString].Controls.Count >= 2 Then
[129]         For k = 0 To Action[sActionString].Controls.Max
[130]           If k = 0 Then sMessage &= "Action = " & sActionString & gb.NewLine
[131]              sMessage &= sSpace & Action[sActionString].Controls[k].Name & gb.NewLine
[132]         Next ' k
[133]     Endif ' Action[sActionString].Controls.Count >= 2 ?
[134]   Next ' sActionString
[136] Message.Title = gb.Tab
[137]   Message.Info(sMessage)
[139] End ' tbSyncList_Click()
[141] Public Sub Form_Close()
[142]   FHelp.Close
[143]   FMain.Close
[144] End ' Form_Close()


Lines 13 to 37 set selected action properties for the 5 associated components.Lines 43 to 57 carry the specifications in the event handler “Action_Activate”.The de-activation of the print function can be found in line 50 if the printing of the image was successful. In lines 18 and 21 this function was de-activated at the start of the programme.After loading an image it could be printed. Therefore, the print function is activated in lines 77 and 78.In lines 104 to 110, all action strings are read out and prepared for display. Since all self-defined action strings begin with a capital letter - in contrast to those pre-defined by Gambas - they receive a “-character.

Figure List of all action strings

The preparation of the compilation of all associated components in lines 127 to 134 is somewhat more extensive, as only those components are included in the compilation that contain at least 2 associated components. The action string 'SynchronList' exists only once - for the component tbSyncList (→ Figure and project MenuAction) and therefore the component tbSyncList is missing in Figure

Figure List of all associated components.

Here you see a source code snippet for a (partial) synchronisation of menu item “Open…” and ToolButton tbOpen that you would have to use if you do not use the Action class:

 Public Sub mnu11OpenImage_Click()
   mnu13PrintImage.Enabled = True
   tbPrint.Enabled = True
 End ' mnu11OpenImage_Click()
 Public Sub tbOpen_Click()
   mnu13PrintImage.Enabled = True
   tbPrint.Enabled = True
 End ' tbOpen_Click()

In contrast, the corresponding source code with the same effect in lines 48 and 50 in the procedure Action_Activate(sActionString As String) looks more than modest.

Regardless of the chosen procedure for synchronising the menu and ToolButton in the ToolBar, you must programme all procedures to give the programme the desired functionality. At the start of the programme you will find only 5 ToolButtons on the toolbar because the print function has been deactivated. You will find the corresponding ToolButton in the toolbar after successfully opening an image file:

Figure Toolbars at runtime

You can trigger the configuration of the ShortCuts with F6, by clicking on the corresponding menu item or ToolButton:

Figure Configuration of short commands


The website uses a temporary session cookie. This technically necessary cookie is deleted when the browser is closed. You can find information on cookies in our privacy policy.
k12/k12.3/k12.3.3/start.txt · Last modified: 01.02.2022 (external edit)

Page Tools