GAMBAS BOOK 3.19.1

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.

Example:

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"
  }
  ...
}

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

Table 12.3.3.1.1: 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.

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"
         ImageOpen
    Case "HelpMe"
         FHelp.Show
    Case "PrintFile"
       ' Procedure for printing the edited file
    Case "FormClose"
         FHelp.Close
         FMain.Close
  End Select ' sActionString
 
End ' Action_Activate(..)

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.

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:

Table 12.3.3.4.1: 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 20.6.4.1:

Illustration 12.3.3.4.1: Menu Editor (detail)

For 5 menus, the appropriate action string from table 20.6.4.1 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 20.6.4.1 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 12.3.3.4.2: Menu and toolbar

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

[1]   ' Gambas class file
[2]
[3] Public Sub Form_Open()
[4]
[5]   FMain.Center
[6]   FMain.Resizable = False
[7]
[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"
[12]
[13]   Action["OpenImage"].Enabled = True
[14]   Action["OpenImage"].Picture = Picture["icon:/16/open"]
[15]   Action["OpenImage"].Shortcut = "Ctrl+O"
[16]   Action["OpenImage"].Visible = True
[17]
[18]   Action["PrintImage"].Enabled = True
[19]   Action["PrintImage"].Picture = Picture["icon:/16/print"]
[20]   Action["PrintImage"].Shortcut = "Ctrl+P"
[21]   Action["PrintImage"].Visible = False ' (!)
[22]
[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"
[28]
[29]   Action["ConfigAction"].Enabled = True
[30]   Action["ConfigAction"].Picture = Picture["icon:/16/access"]
[31]   Action["ConfigAction"].Shortcut = "F6"
[32]   Action["ConfigAction"].Visible = True
[33]
[34]   Action["HelpMe"].Enabled = True
[35]   Action["HelpMe"].Picture = Picture["icon:/16/help"]
[36]   Action["HelpMe"].Shortcut = "F1"
[37]   Action["HelpMe"].Visible = True
[38]
[39]   tbSyncList.Tooltip = "List of" & gb.NewLine & "Synchronised components"
[40]
[41] End ' Form_Open()
[42]
[43] Public Sub Action_Activate(sActionString As String) As Boolean
[44]
[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
[58]
[59] End ' Action_Activate(..)
[60]
[61] Public Sub OpenImage()
[62]
[63]   Dialog.Title = "Import an image file!"
[64]   Dialog.Filter = ["*.png", "Image file"]
[65]
[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 ?
[81]
[82] End ' OpenImage()
[83]
[84] Public Sub PrintImage()
[85]   Message.Info("Insert print routine here!\nThe image is printed.")
[86] End ' PrintImage()
[87]
[88] ' Note: The menu name is also the identifier for the event handler.
[89] Public Sub mnu32HelpNet_Click()
[90]   Desktop.Open("http://www.gambas-buch.de/dw/doku.php?id=k20:k20.6:start")
[91] End ' mnu32HelpNet_Click()
[92]
[93] Public Sub mnu22ListAction_Click()
[94]   Dim iCount As Integer
[95]   Dim sMessage, sTrennLinie, sSpace, sSpace2 As String
[96]
[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
[103]
[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
[111]
[112] Message.Title = gb.tab
[113]   Message.Info(sMessage)
[114]
[115] End ' mnu22ListAction_Click()
[116]
[117] Public Sub tbSyncList_Click()
[118]   Dim iCount, k As Integer = 1
[119]   Dim sActionString, sMessage, sTrennLinie, sSpace As String
[120]
[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
[126]
[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
[135]
[136] Message.Title = gb.Tab
[137]   Message.Info(sMessage)
[138]
[139] End ' tbSyncList_Click()
[140]
[141] Public Sub Form_Close()
[142]   FHelp.Close
[143]   FMain.Close
[144] End ' Form_Close()

Comments:

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 12.3.3.4.3: 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 20.6.4.3 and project MenuAction) and therefore the component tbSyncList is missing in Figure 20.6.4.4.

Figure 12.3.3.4.4: 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()
   ImageOpen()
   mnu13PrintImage.Enabled = True
   tbPrint.Enabled = True
 End ' mnu11OpenImage_Click()
 
 Public Sub tbOpen_Click()
   ImageOpen()
   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 12.3.3.4.5: Toolbars at runtime

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

Figure 12.3.3.4.6: Configuration of short commands