Difference between revisions of "Documentation/BASIC Guide/Properties"

From Apache OpenOffice Wiki
Jump to: navigation, search
(→‎Multi-Page Dialogs)
m
 
(19 intermediate revisions by 7 users not shown)
Line 7: Line 7:
 
}}
 
}}
 
{{DISPLAYTITLE:Properties}}
 
{{DISPLAYTITLE:Properties}}
 +
__NOTOC__
 
== Name and Title ==
 
== Name and Title ==
  
Line 15: Line 16:
 
You can specify the title that appears in the title bar of a dialog with the following model property:
 
You can specify the title that appears in the title bar of a dialog with the following model property:
  
−
;<tt>Model.Title (String)</tt>:dialog title (only applies to dialogs).
+
;<tt>Model.Title (String)</tt>:dialog title (only applies to dialogs)
  
 
== Position and Size ==
 
== Position and Size ==
Line 26: Line 27:
 
;<tt>Model.PositionY (long)</tt>:Y-position of control element, measured from top inner edge of the dialog (in ma units)
 
;<tt>Model.PositionY (long)</tt>:Y-position of control element, measured from top inner edge of the dialog (in ma units)
  
−
To ensure platform independence for the appearance of dialogs, {{OOo}} uses the '''Map AppFont (ma)''' internal unit to specify the position and size within dialogs. An ma unit is defined as being one eighth of the average height of a character from the system font defined in the operating system and one quarter of its width. By using ma units, {{OOo}} ensures that a dialog looks the same on different systems under different system settings.
+
To ensure platform independence for the appearance of dialogs, {{AOo}} uses the '''Map AppFont (ma)''' internal unit to specify the position and size within dialogs. An ma unit is defined as being one eighth of the average height of a character from the system font defined in the operating system and one quarter of its width. By using ma units, {{AOo}} ensures that a dialog looks the same on different systems under different system settings.
  
 
If you want to change the size or position of control elements for runtime, determine the total size of the dialog and adjust the values for the control elements to the corresponding part ratios.
 
If you want to change the size or position of control elements for runtime, determine the total size of the dialog and adjust the values for the control elements to the corresponding part ratios.
  
−
{{Documentation/Note|The Map AppFont (ma) replaces the Twips unit to achieve better platform independence.}}
+
{{Note|The Map AppFont (ma) replaces the Twips unit to achieve better platform independence.}}
  
 
== Focus and Tabulator Sequence ==
 
== Focus and Tabulator Sequence ==
Line 40: Line 41:
 
;<tt>Model.TabIndex (Long)</tt>:position of control element in the order of activation
 
;<tt>Model.TabIndex (Long)</tt>:position of control element in the order of activation
  
−
Finally, the control element provides a <tt>getFocus</tt> method that ensures that the underlying control element receives the focus:
+
Finally, the control element provides a <tt>setFocus</tt> method that ensures that the underlying control element receives the focus:
  
−
;<tt>getFocus</tt>:control element receives the focus (only for dialogs)
+
;<tt>setFocus</tt>:control element receives the focus (only for dialogs)
  
 
== Multi-Page Dialogs ==
 
== Multi-Page Dialogs ==
  
−
A dialog in {{OOo}} can have more than one tab page. The <tt>Step</tt> property of a dialog defines the current tab page of the dialog whereas the <tt>Step</tt> property for a control element specifies the tab page where the control element is to be displayed.
+
A dialog in {{AOo}} can have more than one tab page. The <tt>Step</tt> property of a dialog defines the current tab page of the dialog whereas the <tt>Step</tt> property for a control element specifies the tab page where the control element is to be displayed.
  
−
The <tt>Step</tt>-value of 0 is a special case. If you set this value to zero in a dialog, all of the control elements are visible regardless of their <tt>Step</tt> value. Similarly, if you set this value to zero for a control element, the element is displayed on all of the tab pages in a dialog.
+
The <tt>Step</tt>-value of 0 is a special case. If you set this value to zero in a dialog, all the control elements are visible regardless of their <tt>Step</tt> value. Similarly, if you set this value to zero for a control element, the element is displayed on all the tab pages in a dialog.
  
−
[[Image:documentation_basicguide_dlg_03.gif|none|thumb|500px]]
+
[[Image:documentation_basicguide_dlg_03.gif|none|thumb|500px|Designing Page 1 of the dialog]]
  
 
In the preceding example, you can also assign the <tt>Step</tt> value of 0 to the dividing line as well as the <tt>Cancel</tt>, <tt>Prev</tt>, <tt>Next</tt>, and <tt>Done</tt> buttons to display these elements on all pages. You can also assign the elements to an individual tab page (for example page 1).
 
In the preceding example, you can also assign the <tt>Step</tt> value of 0 to the dividing line as well as the <tt>Cancel</tt>, <tt>Prev</tt>, <tt>Next</tt>, and <tt>Done</tt> buttons to display these elements on all pages. You can also assign the elements to an individual tab page (for example page 1).
Line 56: Line 57:
 
The following program code shows how the <tt>Step</tt> value in event handlers of the <tt>Next</tt> and <tt>Prev</tt> buttons can be increased or reduced and changes the status of the buttons.
 
The following program code shows how the <tt>Step</tt> value in event handlers of the <tt>Next</tt> and <tt>Prev</tt> buttons can be increased or reduced and changes the status of the buttons.
  
−
<source lang="vb">
+
<syntaxhighlight lang="oobas">
−
Sub cmdNext_Initiated
+
Sub cmdNext_Initiated
−
+
 
−
    Dim cmdNext As Object
+
  Dim cmdNext As Object
−
    Dim cmdPrev As Object
+
  Dim cmdPrev As Object
−
+
 
−
    cmdPrev = Dlg.getControl("cmdPrev")
+
  cmdPrev = Dlg.getControl("cmdPrev")
−
    cmdNext = Dlg.getControl("cmdNext")
+
  cmdNext = Dlg.getControl("cmdNext")
−
    cmdPrev.Model.Enabled = Not cmdPrev.Model.Enabled
+
  cmdPrev.Model.Enabled = Not cmdPrev.Model.Enabled
−
    cmdNext.Model.Enabled = False
+
  cmdNext.Model.Enabled = False
−
    Dlg.Model.Step = Dlg.Model.Step + 1
+
  Dlg.Model.Step = Dlg.Model.Step + 1
−
+
 
−
End Sub
+
End Sub
−
+
 
−
Sub cmdPrev_Initiated
+
Sub cmdPrev_Initiated
−
+
 
−
    Dim cmdNext As Object
+
  Dim cmdNext As Object
−
    Dim cmdPrev As Object
+
  Dim cmdPrev As Object
−
+
 
−
    cmdPrev = Dlg.getControl("cmdPrev")
+
  cmdPrev = Dlg.getControl("cmdPrev")
−
    cmdNext = Dlg.getControl("cmdNext")
+
  cmdNext = Dlg.getControl("cmdNext")
−
    cmdPrev.Model.Enabled = False
+
  cmdPrev.Model.Enabled = False
−
    cmdNext.Model.Enabled = True
+
  cmdNext.Model.Enabled = True
−
    Dlg.Model.Step = Dlg.Model.Step - 1
+
  Dlg.Model.Step = Dlg.Model.Step - 1
−
+
 
−
End Sub
+
End Sub
−
</source>
+
</syntaxhighlight>
  
 
A global <tt>Dlg</tt> variable that references an open dialog must be included to make this example possible. The dialog then changes its appearance as follows:
 
A global <tt>Dlg</tt> variable that references an open dialog must be included to make this example possible. The dialog then changes its appearance as follows:
Line 89: Line 90:
  
 
[[Image:documentation_basicguide_dlg_06.gif|none|thumb|400px|Page 2]]
 
[[Image:documentation_basicguide_dlg_06.gif|none|thumb|400px|Page 2]]
 +
{{Tip|You can find an [[Going_further_with_Dialog_and_Component#Multi-Page_Dialog|other OOoBasic example here]].}}
 +
 +
 +
== Dialogs supporting several languages ==
 +
 +
The strings of a Dialog can be localized, see the Developer's Guide chapter [[Documentation/DevGuide/Basic/Dialog_Localization|Dialog Localization]].
 +
  
 +
{{InterWiki Languages BasicGuide|articletitle=Documentation/BASIC Guide/Properties}}
 
{{PDL1}}
 
{{PDL1}}

Latest revision as of 14:10, 30 January 2021


Name and Title

Every control element has its own name that can be queried using the following model property:

Model.Name (String)
control element name

You can specify the title that appears in the title bar of a dialog with the following model property:

Model.Title (String)
dialog title (only applies to dialogs)

Position and Size

You can query the size and position of a control element using the following properties of the model object:

Model.Height (long)
height of control element (in ma units)
Model.Width (long)
width of control element (in ma units)
Model.PositionX (long)
X-position of control element, measured from the left inner edge of the dialog (in ma units)
Model.PositionY (long)
Y-position of control element, measured from top inner edge of the dialog (in ma units)

To ensure platform independence for the appearance of dialogs, Apache OpenOffice uses the Map AppFont (ma) internal unit to specify the position and size within dialogs. An ma unit is defined as being one eighth of the average height of a character from the system font defined in the operating system and one quarter of its width. By using ma units, Apache OpenOffice ensures that a dialog looks the same on different systems under different system settings.

If you want to change the size or position of control elements for runtime, determine the total size of the dialog and adjust the values for the control elements to the corresponding part ratios.

Documentation note.png The Map AppFont (ma) replaces the Twips unit to achieve better platform independence.

Focus and Tabulator Sequence

You can navigate through the control elements in any dialog by pressing the Tab key. The following properties are available in this context in the control elements model:

Model.Enabled (Boolean)
activates the control element
Model.Tabstop (Boolean)
allows the control element to be reached through the Tab key
Model.TabIndex (Long)
position of control element in the order of activation

Finally, the control element provides a setFocus method that ensures that the underlying control element receives the focus:

setFocus
control element receives the focus (only for dialogs)

Multi-Page Dialogs

A dialog in Apache OpenOffice can have more than one tab page. The Step property of a dialog defines the current tab page of the dialog whereas the Step property for a control element specifies the tab page where the control element is to be displayed.

The Step-value of 0 is a special case. If you set this value to zero in a dialog, all the control elements are visible regardless of their Step value. Similarly, if you set this value to zero for a control element, the element is displayed on all the tab pages in a dialog.

Designing Page 1 of the dialog

In the preceding example, you can also assign the Step value of 0 to the dividing line as well as the Cancel, Prev, Next, and Done buttons to display these elements on all pages. You can also assign the elements to an individual tab page (for example page 1).

The following program code shows how the Step value in event handlers of the Next and Prev buttons can be increased or reduced and changes the status of the buttons. 

Sub cmdNext_Initiated
 
   Dim cmdNext As Object
   Dim cmdPrev As Object
 
   cmdPrev = Dlg.getControl("cmdPrev")
   cmdNext = Dlg.getControl("cmdNext")
   cmdPrev.Model.Enabled = Not cmdPrev.Model.Enabled
   cmdNext.Model.Enabled = False
   Dlg.Model.Step = Dlg.Model.Step + 1
 
End Sub
 
Sub cmdPrev_Initiated
 
   Dim cmdNext As Object
   Dim cmdPrev As Object
 
   cmdPrev = Dlg.getControl("cmdPrev")
   cmdNext = Dlg.getControl("cmdNext")
   cmdPrev.Model.Enabled = False
   cmdNext.Model.Enabled = True
   Dlg.Model.Step = Dlg.Model.Step - 1
 
End Sub

A global Dlg variable that references an open dialog must be included to make this example possible. The dialog then changes its appearance as follows:

Page 1
Page 2
Tip.png You can find an other OOoBasic example here.


Dialogs supporting several languages

The strings of a Dialog can be localized, see the Developer's Guide chapter Dialog Localization.


Content on this page is licensed under the Public Documentation License (PDL).
Retrieved from "https://wiki.openoffice.org/w/index.php?title=Documentation/BASIC_Guide/Properties&oldid=247500"
Personal tools