Difference between revisions of "Documentation/BASIC Guide/Events"
m |
|||
(33 intermediate revisions by 4 users not shown) | |||
Line 7: | Line 7: | ||
}} | }} | ||
{{DISPLAYTITLE:Events}} | {{DISPLAYTITLE:Events}} | ||
− | + | __NOTOC__ | |
− | + | {{OOo}} dialogs and forms are based on an event-oriented programming model where you can assign '''event handlers''' to the control elements. An event handler runs a predefined procedure when a particular action occurs. You can also edit documents or open databases with event handling as well as access other control elements. | |
− | {{OOo}} dialogs and forms are based on an event-oriented programming model where you can assign '''event handlers''' to the control elements. An event handler runs a predefined procedure when a particular action occurs | + | |
{{OOo}} control elements recognize different types of events that can be triggered in different situations. These event types can be divided into four groups: | {{OOo}} control elements recognize different types of events that can be triggered in different situations. These event types can be divided into four groups: | ||
− | * '''Mouse control''': Events that correspond to mouse actions (for example, simple mouse movements or a click on a particular screen location) | + | * '''Mouse control''': Events that correspond to mouse actions (for example, simple mouse movements or a click on a particular screen location). |
− | * '''Keyboard control''': Events that are triggered by keyboard strokes | + | * '''Keyboard control''': Events that are triggered by keyboard strokes. |
− | * '''Focus modification''': Events that {{OOo}} | + | * '''Focus modification''': Events that {{OOo}} performs when control elements are activated or deactivated. |
− | * '''Control element-specific events''': Events that only occur in relation to certain control elements | + | * '''Control element-specific events''': Events that only occur in relation to certain control elements. |
− | When you work with events, | + | When you work with events, make sure that you create the associated dialog in the {{OOo}} development environment and that it contains the required control elements or documents (if you apply the events to a form). |
− | [[Image: | + | [[Image:Documentation_basicguide_dlg_03.gif|none|thumb|500px|The OpenOffice.org Basic development environment]] |
− | The | + | The figure above shows the {{OOo}} Basic development environment with a dialog window that contains two list boxes. You can move the data from one list to the other using the buttons between the two list boxes. |
If you want to display the layout on screen, then you should create the associated {{OOo}} Basic procedures so that they can be called up by the event handlers. Even though you can use these procedures in any module, it is best to limit their use to two modules. To make your code easier to read, you should assign meaningful names to these procedures. Jumping directly to a general program procedure from a macro can result in unclear code. Instead, to simplify code maintenance and troubleshooting, you should create another procedure to serve as an entry point for event handling - even if it only executes a single call to the target procedure. | If you want to display the layout on screen, then you should create the associated {{OOo}} Basic procedures so that they can be called up by the event handlers. Even though you can use these procedures in any module, it is best to limit their use to two modules. To make your code easier to read, you should assign meaningful names to these procedures. Jumping directly to a general program procedure from a macro can result in unclear code. Instead, to simplify code maintenance and troubleshooting, you should create another procedure to serve as an entry point for event handling - even if it only executes a single call to the target procedure. | ||
Line 28: | Line 27: | ||
The code in the following example moves an entry from the left to the right list box of a dialog. | The code in the following example moves an entry from the left to the right list box of a dialog. | ||
− | + | <source lang="oobas"> | |
− | + | Sub cmdSelect_Initiated | |
− | + | ||
− | + | Dim lstEntries As Object | |
− | + | Dim lstSelection As Object | |
− | + | ||
− | + | lstEntries = Dlg.getControl("lstEntries") | |
− | + | lstSelection = Dlg.getControl("lstSelection") | |
− | + | ||
− | + | If lstEntries.SelectedItem > 0 Then | |
− | + | lstSelection.AddItem(lstEntries.SelectedItem, 0) | |
− | + | lstEntries.removeItems(lstEntries.SelectItemPos, 1) | |
− | + | Else | |
− | + | Beep | |
− | + | End If | |
+ | |||
+ | End Sub | ||
+ | </source> | ||
If this procedure was created in {{OOo}} Basic, you can assign it to an event required using the property window of the dialog editor. | If this procedure was created in {{OOo}} Basic, you can assign it to an event required using the property window of the dialog editor. | ||
− | [[Image:documentation_basicguide_dlg_02.gif|none|thumb|400px|The Assign | + | [[Image:documentation_basicguide_dlg_02.gif|none|thumb|400px|The Assign Action dialog]] |
− | The | + | The Assign Action dialog lists all of the available Events. To assign a macro to an event: |
+ | # Select the event | ||
+ | # Click '''Macro...''' | ||
+ | # Browse to and select the macro you want to assign | ||
+ | # Click OK | ||
== Parameters == | == Parameters == | ||
Line 56: | Line 62: | ||
In {{OOo}} Basic, you can use object parameters to provide more information about an event to a procedure, for example: | In {{OOo}} Basic, you can use object parameters to provide more information about an event to a procedure, for example: | ||
− | + | <source lang="oobas"> | |
+ | Sub ProcessEvent(Event As Object) | ||
− | + | End Sub | |
+ | </source> | ||
− | The structure and properties of the <tt>Event</tt> object depend on the type of event that triggers the procedure call | + | The structure and properties of the <tt>Event</tt> object depend on the type of event that triggers the procedure call. |
− | Regardless of the type of event, all objects provide access to the relevant control element and its model. The control element can be reached using | + | Regardless of the type of event, all objects provide access to the relevant control element and its model. The control element can be reached using <tt>Event.Source</tt> and its model using <tt>Event.Source.Model</tt>. The dialog can be reached using <tt>Event.Source.Context</tt>. |
− | + | ||
− | + | ||
− | + | ||
− | and its model using | + | |
− | + | ||
− | + | ||
You can use these properties to trigger an event within an event handler. | You can use these properties to trigger an event within an event handler. | ||
Line 79: | Line 81: | ||
;<tt>Mouse moved while key pressed</tt>:user drags mouse while holding down a key | ;<tt>Mouse moved while key pressed</tt>:user drags mouse while holding down a key | ||
;<tt>Mouse button pressed</tt>:user presses a mouse button | ;<tt>Mouse button pressed</tt>:user presses a mouse button | ||
+ | {{Documentation/Note|This event is also used for notifying requests for a popup context menu on the control. In this case, the member <tt>PopupTrigger</tt> of the event passed to your macro function will be <tt>TRUE</tt>. In particular, if such a request is made by pressing the right mouse button on the control, the event will be fired twice: once for the popup menu request, and once for the real mouse event. If you are interested in only the mouse click, your macro should ignore all calls where <tt>PopupTrigger</tt> is <tt>TRUE</tt>.}} | ||
;<tt>Mouse button released</tt>:user releases a mouse button | ;<tt>Mouse button released</tt>:user releases a mouse button | ||
;<tt>Mouse outside</tt>:user moves mouse outside of the current window | ;<tt>Mouse outside</tt>:user moves mouse outside of the current window | ||
− | The structure of the associated event objects is defined in the < | + | The structure of the associated event objects is defined in the <idl>com.sun.star.awt.MouseEvent</idl> structure which provides the following information: |
− | ;<tt>Buttons (short)</tt>:button pressed (one or more constants in accordance with < | + | ;<tt>Buttons (short)</tt>:button pressed (one or more constants in accordance with <idl>com.sun.star.awt.MouseButton</idl>) |
;<tt>X (long)</tt>:X-coordinate of mouse, measured in pixels from the top left corner of the control element | ;<tt>X (long)</tt>:X-coordinate of mouse, measured in pixels from the top left corner of the control element | ||
;<tt>Y (long)</tt>:Y-coordinate of mouse, measured in pixels from the top left corner of the control element | ;<tt>Y (long)</tt>:Y-coordinate of mouse, measured in pixels from the top left corner of the control element | ||
− | ;<tt>ClickCount (long)</tt>:number of clicks associated with the mouse event (if {{OOo}} can respond fast enough, <tt>ClickCount</tt> is also 1 for a double-click because only an individual event is initiated) | + | ;<tt>ClickCount (long)</tt>:number of clicks associated with the mouse event (if {{OOo}} can respond fast enough, <tt>ClickCount</tt> is also 1 for a double-click because only an individual event is initiated) |
− | The constants defined in < | + | The constants defined in <idl>com.sun.star.awt.MouseButton</idl> for the mouse buttons are: |
;<tt>LEFT</tt>:left mouse button | ;<tt>LEFT</tt>:left mouse button | ||
Line 97: | Line 100: | ||
The following example outputs the mouse position as well as the mouse button that was pressed: | The following example outputs the mouse position as well as the mouse button that was pressed: | ||
− | + | <source lang="oobas"> | |
− | + | Sub MouseUp(Event As Object) | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
+ | Dim Msg As String | ||
− | + | Msg = "Keys: " | |
+ | If Event.Buttons AND com.sun.star.awt.MouseButton.LEFT Then | ||
+ | Msg = Msg & "LEFT " | ||
+ | End If | ||
+ | If Event.Buttons AND com.sun.star.awt.MouseButton.RIGHT Then | ||
+ | Msg = Msg & "RIGHT " | ||
+ | End If | ||
+ | |||
+ | If Event.Buttons AND com.sun.star.awt.MouseButton.MIDDLE Then | ||
+ | Msg = Msg & "MIDDLE " | ||
+ | End If | ||
+ | |||
+ | Msg = Msg & Chr(13) & "Position: " | ||
+ | Msg = Msg & Event.X & "/" & Event.Y | ||
+ | MsgBox Msg | ||
+ | |||
+ | End Sub | ||
+ | </source> | ||
+ | |||
+ | {{Documentation/VBAnote|The VBA <tt>Click</tt> and <tt>Doubleclick</tt> events are not available in {{OOo}} Basic. Instead use the {{OOo}} Basic <tt>MouseUp</tt> event for the <tt>click</tt> event and imitate the <tt>Doubleclick</tt> event by changing the application logic.}} | ||
== Keyboard Events == | == Keyboard Events == | ||
Line 128: | Line 131: | ||
The following keyboard events are available in {{OOo}} Basic: | The following keyboard events are available in {{OOo}} Basic: | ||
− | ;<tt>Key pressed</tt>:user presses a key | + | ;<tt>Key pressed</tt>:user presses a key. |
;<tt>Key released</tt>:user releases a key | ;<tt>Key released</tt>:user releases a key | ||
− | Both events relate to | + | Both events relate to logical key actions and not to physical actions. If the user presses several keys to output a single character (for example, to add an accent to a character), then {{OOo}} Basic only creates one event. |
A single key action on a modification key, such as the Shift key or the Alt key does not create an independent event. | A single key action on a modification key, such as the Shift key or the Alt key does not create an independent event. | ||
Line 137: | Line 140: | ||
Information about a pressed key is provided by the event object that {{OOo}} Basic supplies to the procedure for event handling. It contains the following properties: | Information about a pressed key is provided by the event object that {{OOo}} Basic supplies to the procedure for event handling. It contains the following properties: | ||
− | ;<tt>KeyCode (short)</tt>:code of the pressed key (default values in accordance with < | + | ;<tt>KeyCode (short)</tt>:code of the pressed key (default values in accordance with <idl>com.sun.star.awt.Key</idl>) |
;<tt>KeyChar (String)</tt>:character that is entered (taking the modification keys into consideration) | ;<tt>KeyChar (String)</tt>:character that is entered (taking the modification keys into consideration) | ||
− | The following example uses the <tt>KeyCode</tt> property to establish if the Enter key, the Tab key, or one of the other control keys has been pressed. If one of these keys has been pressed, the name of the key is | + | The following example uses the <tt>KeyCode</tt> property to establish if the Enter key, the Tab key, or one of the other control keys has been pressed. If one of these keys has been pressed, the name of the key is returned, otherwise the character that was typed is returned: |
− | + | <source lang="oobas"> | |
− | + | Sub KeyPressed(Event As Object) | |
− | + | ||
− | + | Dim Msg As String | |
− | + | ||
− | + | Select Case Event.KeyCode | |
− | + | Case com.sun.star.awt.Key.RETURN | |
− | + | Msg = "Return pressed" | |
− | + | Case com.sun.star.awt.Key.TAB | |
− | + | Msg = "Tab pressed" | |
− | + | Case com.sun.star.awt.Key.DELETE | |
− | + | Msg = "Delete pressed" | |
− | + | Case com.sun.star.awt.Key.ESCAPE | |
− | + | Msg = "Escape pressed" | |
− | + | Case com.sun.star.awt.Key.DOWN | |
− | + | Msg = "Down pressed" | |
− | + | Case com.sun.star.awt.Key.UP | |
− | + | Msg = "Up pressed" | |
− | + | Case com.sun.star.awt.Key.LEFT | |
− | + | Msg = "Left pressed" | |
− | + | Case com.sun.star.awt.Key.RIGHT | |
− | + | Msg = "Right pressed" | |
− | + | Case Else | |
− | + | Msg = "Character " & Event.KeyChar & " entered" | |
− | + | End Select | |
− | + | MsgBox Msg | |
− | + | ||
+ | End Sub | ||
+ | </source> | ||
− | Information about other keyboard constants can be found in the API Reference under the < | + | Information about other keyboard constants can be found in the API Reference under the <idl>com.sun.star.awt.Key</idl> group of constants. |
== Focus Events == | == Focus Events == | ||
Line 181: | Line 186: | ||
The <tt>Event</tt> objects for the focus events are structured as follows: | The <tt>Event</tt> objects for the focus events are structured as follows: | ||
− | ;<tt>FocusFlags (short)</tt>:cause of focus change (default value in accordance with < | + | ;<tt>FocusFlags (short)</tt>:cause of focus change (default value in accordance with <idl>com.sun.star.awt.FocusChangeReason</idl> ) |
;<tt>NextFocus (Object)</tt>:object that receives focus (only for the <tt>When losing focus</tt> event) | ;<tt>NextFocus (Object)</tt>:object that receives focus (only for the <tt>When losing focus</tt> event) | ||
;<tt>Temporary (Boolean)</tt>:the focus is temporarily lost | ;<tt>Temporary (Boolean)</tt>:the focus is temporarily lost | ||
Line 195: | Line 200: | ||
When you work with events, note that some events, such as the <tt>When initiating</tt> event, can be initiated each time you click the mouse on some control elements (for example, on radio buttons). No action is performed to check if the status of the control element has actually changed. To avoid such “blind events”, save the old control element value in a global variable, and then check to see if the value has changed when an event is executing. | When you work with events, note that some events, such as the <tt>When initiating</tt> event, can be initiated each time you click the mouse on some control elements (for example, on radio buttons). No action is performed to check if the status of the control element has actually changed. To avoid such “blind events”, save the old control element value in a global variable, and then check to see if the value has changed when an event is executing. | ||
+ | |||
+ | The <tt>When initiating</tt> event is also noteworthy for the following reasons: | ||
+ | *This event is initiated by either a key-press or a mouse button. Thus, it provides a consistent interface for users who navigate by mouse or by keyboard. | ||
+ | *When the <tt>Repeat</tt> property of a command button is set to <tt>True</tt>, this event is the one which is repeatedly sent, as long as the triggering action (key down or mouse-button down) remains in effect. | ||
The properties for the <tt>Item Status Changed</tt> event are: | The properties for the <tt>Item Status Changed</tt> event are: | ||
Line 202: | Line 211: | ||
;<tt>ItemId (long)</tt>:ID of entry | ;<tt>ItemId (long)</tt>:ID of entry | ||
− | + | {{InterWiki Languages BasicGuide|articletitle=Documentation/BASIC Guide/Events}} | |
{{PDL1}} | {{PDL1}} |
Revision as of 16:28, 17 March 2013
Apache OpenOffice dialogs and forms are based on an event-oriented programming model where you can assign event handlers to the control elements. An event handler runs a predefined procedure when a particular action occurs. You can also edit documents or open databases with event handling as well as access other control elements.
Apache OpenOffice control elements recognize different types of events that can be triggered in different situations. These event types can be divided into four groups:
- Mouse control: Events that correspond to mouse actions (for example, simple mouse movements or a click on a particular screen location).
- Keyboard control: Events that are triggered by keyboard strokes.
- Focus modification: Events that Apache OpenOffice performs when control elements are activated or deactivated.
- Control element-specific events: Events that only occur in relation to certain control elements.
When you work with events, make sure that you create the associated dialog in the Apache OpenOffice development environment and that it contains the required control elements or documents (if you apply the events to a form).
The figure above shows the Apache OpenOffice Basic development environment with a dialog window that contains two list boxes. You can move the data from one list to the other using the buttons between the two list boxes.
If you want to display the layout on screen, then you should create the associated Apache OpenOffice Basic procedures so that they can be called up by the event handlers. Even though you can use these procedures in any module, it is best to limit their use to two modules. To make your code easier to read, you should assign meaningful names to these procedures. Jumping directly to a general program procedure from a macro can result in unclear code. Instead, to simplify code maintenance and troubleshooting, you should create another procedure to serve as an entry point for event handling - even if it only executes a single call to the target procedure.
The code in the following example moves an entry from the left to the right list box of a dialog.
Sub cmdSelect_Initiated Dim lstEntries As Object Dim lstSelection As Object lstEntries = Dlg.getControl("lstEntries") lstSelection = Dlg.getControl("lstSelection") If lstEntries.SelectedItem > 0 Then lstSelection.AddItem(lstEntries.SelectedItem, 0) lstEntries.removeItems(lstEntries.SelectItemPos, 1) Else Beep End If End Sub
If this procedure was created in Apache OpenOffice Basic, you can assign it to an event required using the property window of the dialog editor.
The Assign Action dialog lists all of the available Events. To assign a macro to an event:
- Select the event
- Click Macro...
- Browse to and select the macro you want to assign
- Click OK
Parameters
The occurrence of a particular event is not always enough for an appropriate response. Additional information may be required. For example, to process a mouse click, you may need the screen position where the mouse button was pressed.
In Apache OpenOffice Basic, you can use object parameters to provide more information about an event to a procedure, for example:
Sub ProcessEvent(Event As Object) End Sub
The structure and properties of the Event object depend on the type of event that triggers the procedure call.
Regardless of the type of event, all objects provide access to the relevant control element and its model. The control element can be reached using Event.Source and its model using Event.Source.Model. The dialog can be reached using Event.Source.Context.
You can use these properties to trigger an event within an event handler.
Mouse Events
Apache OpenOffice Basic recognizes the following mouse events:
- Mouse moved
- user moves mouse
- Mouse moved while key pressed
- user drags mouse while holding down a key
- Mouse button pressed
- user presses a mouse button
- Mouse button released
- user releases a mouse button
- Mouse outside
- user moves mouse outside of the current window
The structure of the associated event objects is defined in the com.sun.star.awt.MouseEvent structure which provides the following information:
- Buttons (short)
- button pressed (one or more constants in accordance with com.sun.star.awt.MouseButton)
- X (long)
- X-coordinate of mouse, measured in pixels from the top left corner of the control element
- Y (long)
- Y-coordinate of mouse, measured in pixels from the top left corner of the control element
- ClickCount (long)
- number of clicks associated with the mouse event (if Apache OpenOffice can respond fast enough, ClickCount is also 1 for a double-click because only an individual event is initiated)
The constants defined in com.sun.star.awt.MouseButton for the mouse buttons are:
- LEFT
- left mouse button
- RIGHT
- right mouse button
- MIDDLE
- middle mouse button
The following example outputs the mouse position as well as the mouse button that was pressed:
Sub MouseUp(Event As Object) Dim Msg As String Msg = "Keys: " If Event.Buttons AND com.sun.star.awt.MouseButton.LEFT Then Msg = Msg & "LEFT " End If If Event.Buttons AND com.sun.star.awt.MouseButton.RIGHT Then Msg = Msg & "RIGHT " End If If Event.Buttons AND com.sun.star.awt.MouseButton.MIDDLE Then Msg = Msg & "MIDDLE " End If Msg = Msg & Chr(13) & "Position: " Msg = Msg & Event.X & "/" & Event.Y MsgBox Msg End Sub
Keyboard Events
The following keyboard events are available in Apache OpenOffice Basic:
- Key pressed
- user presses a key.
- Key released
- user releases a key
Both events relate to logical key actions and not to physical actions. If the user presses several keys to output a single character (for example, to add an accent to a character), then Apache OpenOffice Basic only creates one event.
A single key action on a modification key, such as the Shift key or the Alt key does not create an independent event.
Information about a pressed key is provided by the event object that Apache OpenOffice Basic supplies to the procedure for event handling. It contains the following properties:
- KeyCode (short)
- code of the pressed key (default values in accordance with com.sun.star.awt.Key)
- KeyChar (String)
- character that is entered (taking the modification keys into consideration)
The following example uses the KeyCode property to establish if the Enter key, the Tab key, or one of the other control keys has been pressed. If one of these keys has been pressed, the name of the key is returned, otherwise the character that was typed is returned:
Sub KeyPressed(Event As Object) Dim Msg As String Select Case Event.KeyCode Case com.sun.star.awt.Key.RETURN Msg = "Return pressed" Case com.sun.star.awt.Key.TAB Msg = "Tab pressed" Case com.sun.star.awt.Key.DELETE Msg = "Delete pressed" Case com.sun.star.awt.Key.ESCAPE Msg = "Escape pressed" Case com.sun.star.awt.Key.DOWN Msg = "Down pressed" Case com.sun.star.awt.Key.UP Msg = "Up pressed" Case com.sun.star.awt.Key.LEFT Msg = "Left pressed" Case com.sun.star.awt.Key.RIGHT Msg = "Right pressed" Case Else Msg = "Character " & Event.KeyChar & " entered" End Select MsgBox Msg End Sub
Information about other keyboard constants can be found in the API Reference under the com.sun.star.awt.Key group of constants.
Focus Events
Focus events indicate if a control element receives or loses focus. You can use these events to, for example, determine if a user has finished processing a control element so that you can update other elements of a dialog. The following focus events are available:
- When receiving focus
- element receives focus
- When losing focus
- element loses focus
The Event objects for the focus events are structured as follows:
- FocusFlags (short)
- cause of focus change (default value in accordance with com.sun.star.awt.FocusChangeReason )
- NextFocus (Object)
- object that receives focus (only for the When losing focus event)
- Temporary (Boolean)
- the focus is temporarily lost
Control Element-Specific Events
In addition to the preceding events, which are supported by all control elements, there are also some control element-specific events that are only defined for certain control elements. The most important of these events are:
- When Item Changed
- the value of a control element changes
- Item Status Changed
- the status of a control element changes
- Text modified
- the text of a control element changes
- When initiating
- an action that can be performed when the control element is triggered (for example, a button is pressed)
When you work with events, note that some events, such as the When initiating event, can be initiated each time you click the mouse on some control elements (for example, on radio buttons). No action is performed to check if the status of the control element has actually changed. To avoid such “blind events”, save the old control element value in a global variable, and then check to see if the value has changed when an event is executing.
The When initiating event is also noteworthy for the following reasons:
- This event is initiated by either a key-press or a mouse button. Thus, it provides a consistent interface for users who navigate by mouse or by keyboard.
- When the Repeat property of a command button is set to True, this event is the one which is repeatedly sent, as long as the triggering action (key down or mouse-button down) remains in effect.
The properties for the Item Status Changed event are:
- Selected (long)
- currently selected entry
- Highlighted (long)
- currently highlighted entry
- ItemId (long)
- ID of entry
Content on this page is licensed under the Public Documentation License (PDL). |