Special Behavior of Apache OpenOffice Basic

OpenOffice.org Developer's Guide

OpenOffice.org Basic

< Previous Section

Next Section >

• First Steps with OpenOffice.org Basic

• Creating a Module in a Standard Library
• Writing and Debugging a Basic UNO program
• Calling a Sub from the User Interface
• Creating Dialogs
• Adding Event Handlers
• AutoPilot Dialogs

• OpenOffice.org Basic IDE

• Managing Basic and Dialog Libraries

• OpenOffice.org Basic Macros Dialog

• Displayed Information
• Buttons

• OpenOffice.org Basic Macro Organizer Dialog

• Modules
• Dialogs
• Libraries

• Basic IDE Window

• Basic Source Editor and Debugger
• Dialog Editor

• Assigning Macros to GUI Events
• Dialog Localization

• Technical Background

• Features of OpenOffice.org Basic

• Functional Range Overview

• Screen I/O Functions
• File I/O
• Date and Time Functions
• Numeric Functions
• String Functions
• Specific UNO Functions

• Accessing the UNO API
• Special Behavior of OpenOffice.org Basic

• Advanced Library Organization

• General Structure
• Accessing Libraries from Basic
• Variable Scopes

• Programming Dialogs and Dialog Controls

• Dialog Handling

• Showing a Dialog
• Getting the Dialog Model
• Dialog as Control Container
• Dialog Properties
• Common Properties
• Multi-Page Dialogs

• Dialog Controls

• Command Button
• Image Control
• Check Box
• Option Button
• Label Field
• Text Field
• List Box
• Combo Box
• Horizontal/Vertical Scroll Bar
• Group Box
• Progress Bar
• Horizontal/Vertical Line
• Date Field
• Time Field
• Numeric Field
• Currency Field
• Formatted Field
• Pattern Field
• File Control

• Creating Dialogs at Runtime
• Library File Structure

• Application Library Container
• Document Library Container

• Library Deployment

< Previous Page

Next Page >

Threading and rescheduling of Apache OpenOffice Basic differs from other languages which must be taken into consideration.

Threads

Apache OpenOffice Basic does not support threads:

• In situations it may be necessary to create new threads to access UNO components in a special way. This is not possible in Apache OpenOffice Basic.
• Apache OpenOffice Basic is unable to control threads. If two threads use the Basic runtime system simultaneously, the result will be undefined results or even a crash. Please take precautions.

Rescheduling

The Apache OpenOffice Basic runtime system reschedules regularly. It allows system messages to be dispatched continuously that have been sent to the Apache OpenOffice process during the runtime of a Basic module. This is necessary to allow repainting operations, and access to controls and menus during the runtime of a Basic script as Basic runs in the Apache OpenOffice main thread. Otherwise, it would not be possible to stop a running Basic script by clicking the corresponding button on the toolbar.

This behavior has an important consequence. Any system message, for example, clicking a push button control, can result in a callback into Basic if an corresponding event is specified. The Basic programmer must be aware of the fact that this can take place at any point of time when a script is running.

The following example shows how this effects the state of the Basic runtime system:

  Dim EndLoop As Boolean
  Dim AllowBreak As Boolean
 
  ' Main sub, the execution starts here
      Sub Main
      ' Initialize flags
      EndLoop = FALSE
      AllowBreak = FALSE
 
      Macro1' calls sub Macro1
  End Sub
 
  ' Sub called by main
  Sub Macro1
      Dim a
      While Not EndLoop
          ' Toggle flags permanently
          AllowBreak = TRUE
          AllowBreak = FALSE
      Wend
      Print "Ready!"
  End Sub
 
  ' Sub assigned to a push button in a writer document
  Sub Break
  If AllowBreak = TRUE Then
      EndLoop = TRUE
      EndIf
  End Sub

When Sub Main in this Basic module is executed, the two Boolean variables EndLoop and AllowBreak are initialized. Then Sub Macro1 is called where the execution runs into a loop. The loop is executed until the EndLoop flag is set to TRUE. This is done in Sub Break that is assigned to a push button in a writer document, but the EndLoop flag can only be set to TRUE if the AllowBreak flag is also TRUE. This flag is permanently toggled in the loop in Sub Macro1.

The program execution may or may not be stopped if the push button is clicked. It depends on the point of time the push button is clicked. If the Basic runtime system has just executed the AllowBreak = TRUE statement, the execution is stopped because the If condition in Sub Break is TRUE and the EndLoop flag can be set to TRUE. If the push button is clicked when the AllowBreak variable is FALSE, the execution is not stopped. The Basic runtime system reschedules permanently, therefore it is unpredictable. This is an example to show what problems may result from the Basic rescheduling mechanism.

Callbacks to Basic that result from rescheduling have the same effect as if the Sub specified in the event had been called directly from the position in the Basic code that is executed in the moment the rescheduling action leading to the callback takes place. In this example, the Basic call stack looks like this, if a breakpoint is placed in the Sub Break:

 Basic         Native code
 
 0: Break  <---  Callback due to push button event
 1: Macro1 --->  Reschedule()
 2: Main

With the call to the native Reschedule method, the Basic runtime system is left and reentered when the push button events in a Callback to Basic. On the Basic stack this looks like a direct call from Sub Macro1 to Sub Break.

A similar situation occurs when a program raises a dialog using the execute method of the dialog object returned by CreateUnoDialog(). See Programming Dialogs and Dialog Controls. In this case, the Basic runtime system does not reschedule, but messages are processed by the dialog's message loop that also result in callbacks to Basic. When the Basic runtime system is called back due to an event at a dialog control, the resulting Basic stack looks analogous. For example:

  Sub Main
      Dim oDialog
      oDialog = CreateUnoDialog( ... )
      oDialog.execute()
  End Sub
 
  Sub DoIt
      ...
  End Sub

If Sub DoIt is specified to be executed if an event occurs for one of the dialog controls, the Basic call stack looks like this if a breakpoint is placed in Sub DoIt:

 Basic        Native code
 
 0: DoIt <--- Callback due to control event
 1: Main ---> execute() ---> Reschedule()

There is also a difference to the rescheduling done directly by the Basic runtime system. The rescheduling done by the dialog's message loop can not result in unpredictable behavior, because the Basic runtime system has called the dialog's execute method and waits for its return. It is in a well-defined state.

Content on this page is licensed under the Public Documentation License (PDL).