Directive # Pragma Directives --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ## Description Used to suspend and/or override actions to improve code execution times, issue warnings or error messages, and change/modify other normal operations. When a pragma directive is used to disable an automatic task, the task remains off until the end of the method in which it is called (or is enabled by calling it again and specifying `True`), but not in other methods that might be called within the original method. Some pragma commands can be turned on and off within a method. Refer to the list below for specifics. ## Usage ``` xojo #Pragma Directive ``` **or** ``` xojo #Pragma Directive True False ``` **or** ``` xojo #Pragma Directive StdCall CDecl ' Directive: X86CallingConvention ``` **or** ``` xojo #Pragma Directive "Message" ' Directive: Error or Warning ``` **or** ``` xojo #Pragma Directive VariableName ' Directive: Unused ``` | Directive | Description | |------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | BackgroundTasks | Enables or disables auto-yield to background threads. In addition to the pragma directive, specify `True` or `False`. Setting this directive to `False` is the same as using DisableBackgroundTasks. You may place this pragma anywhere within the method to enable or disable background threads as necessary. | | BoundsChecking | Enables or disables bounds checking. In addition to the pragma directive, specify `True` or `False`. Specifying `False` is the same as using DisableBoundsChecking. You may place this pragma anywhere within the method to enable or disable bounds checking as necessary. | | BreakOnExceptions | Used to override the BreakOnExceptions menu item in the IDE. The possible values are: `True`, `False`, and **Default**. You may place this pragma anywhere within the method to enable or disable breaking on exceptions as necessary. | | Debug | Enables or disables debugging the method. This can be useful when testing the performance of your code from the IDE. The possible values are: `True` (debugging enabled, the default) and `False` (debugging disabled). | | DisableBackgroundTasks | Used to disable calls to the framework inside of loop iterations to see if it needs to switch threads or perform other tasks (such as polling the debugger socket in a debug build). It is specific to the scope the pragma is in and does not affect other methods you may call from your method. It also does not disable preemptive thread switching in the OS itself. Using this pragma can speed up very processor-intensive operations. Do not use DisableBackgroundTasks within web applications as it will prevent other sessions from running until the background tasks are resumed. This could cause sessions to disconnect or other undesired behavior. | | DisableBoundsChecking | Used to turn off array bounds checking on array index values in code after the `#Pragma`. | | Error | Used to generate a compile error manually, preventing your project from compiling. Useful for reminding you of code you have to update. A `String` is required to describe the error. | | NilObjectChecking | Controls whether to automatically check objects for `Nil` before accessing properties and calling methods. In addition to the pragma directive, specify `True` or `False`. | | StackOverflowChecking | Controls whether to check for stack overflows. In addition to the pragma directive, specify `True` or `False`. You may place this pragma anywhere within the method to enable or disable stack overflow checking as necessary. | | Unused *VariableName* | Controls whether Analyze Project will test for the passed unused variable. *VariableName* can be a local variable, method parameter, or event parameter. You must pass the variable or parameter you do not want to test. The pragma can be used only after the variable has been declared. Also, you cannot pass a list of variables. Use a separate `#Pragma` statement for each variable. You can also turn off checking within the Issues pane by clicking the Type Filter button In the Issues toolbar and deselecting the checks for unknown local variable, method parameter, or event parameter. | | Warning | Used to issue a warning manually. Useful to remind you of code to fix. This warning only appears when you check your project for errors. A `String` is required to describe the warning. | | X86CallingConvention | Accepts either **StdCall** or **CDecl**, not `True` or `False`. Allows you to determine which calling convention a method will be compiled with on x86. This allows you to write callback functions on Windows, which typically require the StdCall calling convention. |
Note
BreakOnExceptions and Debug are not currently supported for Android.
## Notes The Pragma Directives BackgroundTasks, BoundsChecking, BreakOnExceptions, NilObjectChecking and StackOverflowChecking can be enabled or disabled within the method. The setting is tied to the enclosing scope. So, for example, if it's in an 'if' block, it will be reset to the outer value when the scope is exited. ## Sample code This example disables background tasks for the inner loop, but leave them enabled for the outer loop: ``` xojo For y = 0 To Height #Pragma BackgroundTasks False For x = 0 To Width //...process some pixels... Next #Pragma BackgroundTasks True Next ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The following example shows how the BreakOnExceptions pragma can be used to turn off the feature for a particular code snippet. This is handy when you have a specific exception that you do not want to cause the debugger to appear: ``` xojo #Pragma BreakOnExceptions False Try Var f As FolderItem f.Visible = True Catch err As NilObjectException End Try ' Reset to its default state #Pragma BreakOnExceptions Default ``` ## Compatibility | | | |-----------------------|-----| | **Project Types** | All | | **Operating Systems** | All |