stddialog (lx_stddialog.hpp)
Contents
- 1 ILxAsyncMonitorInfo
- 1.1 (1) SDK: LXu_ASYNCMONITORINFO, etc. defines
- 1.2 (2) SDK: AsyncMonitorInfo::System, etc.
- 1.3 (3) SDK: AsyncMonitorInfo::Progress
- 1.4 (4) SDK: AsyncMonitorInfo::OverallProgress
- 1.5 (5) SDK: AsyncMonitorInfo::Parent, etc.
- 1.6 (6) SDK: AsyncMonitorInfo::Identifier
- 1.7 (7) SDK: AsyncMonitorInfo::CanAbort
- 1.8 (8) SDK: AsyncMonitorInfo::Abort
- 1.9 (9) SDK: AsyncMonitorInfo::IsAborted
- 1.10 (10) PY: empty AsyncMonitorInfo user class
- 2 ILxAsyncMonitorInfo1 (Legacy Interface)
- 3 ILxAsyncMonitorSystem
- 4 Standard Dialog Service
- 4.1 (17) SDK: LXa_STDDIALOGSERVICE, etc. defines
- 4.2 (18) SDK: StdDialogService::ScriptQuery
- 4.3 Monitors
- 4.4 Messages and Message Dialogs
- 4.4.1 (21) SDK: StdDialogService::MessageAllocate
- 4.4.2 (22) SDK: CLxUser_StdDialogService::MessageAllocate method
- 4.4.3 (23) SDK: LXeMSGDIALOG_AS_OKCANCEL, etc. defines
- 4.4.4 (24) SDK: LXeMSGDIALOG_EMPTY, etc. defines
- 4.4.5 (25) SDK: StdDialogService::MessageOpen
- 4.4.6 (26) SDK: LXeMSGDIALOG_OK, etc. defines
- 4.4.7 (27) SDK: Sync Monitor Username Example
- 4.5 Asynchronous Monitors
- 4.6 File Dialogs
- 4.6.1 (32) SDK: StdDialogService::FileDialog
- 4.6.2 (33) SDK: LXeFILEDIALOG_BADCLASS, etc. defines
- 4.6.3 (34) SDK: FileDialogClient::Flags
- 4.6.4 (35) SDK: LXfFILEDIALOG_LOAD, etc. defines
- 4.6.5 (36) SDK: FileDialogClient::Title
- 4.6.6 (37) SDK: FileDialogClient::FileClass
- 4.6.7 (38) SDK: FileDialogClient::ContextString
- 4.6.8 (39) SDK: FileDialogClient::FileFormat
- 4.6.9 (40) SDK: FileDialogClient::StartPath
- 4.6.10 (41) SDK: FileDialogClient::ResultPath
- 4.6.11 (42) SDK: FileDialogClient::ResultFormat
- 4.6.12 (43) SDK: LXu_FILEDIALOGCLIENT define
- 4.6.13 Nexus 11.1
ILxAsyncMonitorInfo
Asynchronous monitors provide can provide information about their current state. In fact, you can tell the difference between a standard monitor and an async monitor based on either it exposes this interface. This is primarily used to implement the Activity View.
(1) SDK: LXu_ASYNCMONITORINFO, etc. defines
#define LXu_ASYNCMONITORINFO "79f3c06f-f36d-477d-b946-f6f78a838230" #define LXa_ASYNCMONITORINFO "asyncmonitorinfo"
Get the system and title of the monitor.
(2) SDK: AsyncMonitorInfo::System, etc.
LXxMETHOD( LxResult, System) ( LXtObjectID self, const char **system); LXxMETHOD( LxResult, Title) ( LXtObjectID self, const char **title);
Get the current progress of this single monitor, ignoring child monitors.
(3) SDK: AsyncMonitorInfo::Progress
LXxMETHOD( LxResult, Progress) ( LXtObjectID self, double **progress);
This is similar, but takes into account sub-monitors to provide an overall progress value.
(4) SDK: AsyncMonitorInfo::OverallProgress
LXxMETHOD( LxResult, OverallProgress) ( LXtObjectID self, double **progress);
Get the parent and child of the monitor. This fails with NOTAVAILABLE if there is no parent or child. These objects must be released when no longer needed.
(5) SDK: AsyncMonitorInfo::Parent, etc.
LXxMETHOD( LxResult, Parent) ( LXtObjectID self, void **ppvObj); LXxMETHOD( LxResult, Child) ( LXtObjectID self, void **ppvObj);
This returns a unique identifier string for the monitor, mostly to make it easier to address from things like the Activity View commands.
(6) SDK: AsyncMonitorInfo::Identifier
LXxMETHOD( LxResult, Identifier) ( LXtObjectID self, const char **ident);
Returns LXe_TRUE if the monitor can be aborted. This is purely a UI construct, and determiens if a root-level monitor should draw the abort widget. It is always false on sub-monitors, and Abort() can still be called, in which case IsAborted() will return true.
(7) SDK: AsyncMonitorInfo::CanAbort
LXxMETHOD( LxResult, CanAbort) ( LXtObjectID self);
Tell the monitor to abort. This simply sets the abort flag, which is returned by IsAborted() and ILxMonitor::Step().
(8) SDK: AsyncMonitorInfo::Abort
LXxMETHOD( LxResult, Abort) ( LXtObjectID self);
This returns LXe_TRUE if aborted, and LXe_FALSE if it is still running.
(9) SDK: AsyncMonitorInfo::IsAborted
LXxMETHOD( LxResult, IsAborted) ( LXtObjectID self);
Empty AsyncMonitorInfo Python user class.
(10) PY: empty AsyncMonitorInfo user class
pass
ILxAsyncMonitorInfo1 (Legacy Interface)
This interface was retired in modo 11.1, and was replaced with an updated one that adds the CanAbort() method.
(11) SDK: LXu_ASYNCMONITORINFO1 define
#define LXu_ASYNCMONITORINFO1 "adf5bb35-7180-4d6e-9348-49206ae7e6ca"
(12) SDK: AsyncMonitorInfo1::System, etc.
LXxMETHOD( LxResult, System) ( LXtObjectID self, const char **system); LXxMETHOD( LxResult, Title) ( LXtObjectID self, const char **title); LXxMETHOD( LxResult, Progress) ( LXtObjectID self, double **progress); LXxMETHOD( LxResult, OverallProgress) ( LXtObjectID self, double **progress); LXxMETHOD( LxResult, Parent) ( LXtObjectID self, void **ppvObj); LXxMETHOD( LxResult, Child) ( LXtObjectID self, void **ppvObj); LXxMETHOD( LxResult, Identifier) ( LXtObjectID self, const char **ident); LXxMETHOD( LxResult, Abort) ( LXtObjectID self); LXxMETHOD( LxResult, IsAborted) ( LXtObjectID self);
ILxAsyncMonitorSystem
Async monitors are organized by the system they belong to. An object representing this list provides this simple interface.
Note that the methods in this interface should only be used from the main thread.
(13) SDK: LXu_ASYNCMONITORSYSTEM, etc. defines
#define LXu_ASYNCMONITORSYSTEM "c573842a-d4fd-48eb-8fb0-078a721e5e0f" #define LXa_ASYNCMONITORSYSTEM "asyncmonitorsystem"
Get the name of the system.
(14) SDK: AsyncMonitorSystem::Name
LXxMETHOD( LxResult, Name) ( LXtObjectID self, const char **name);
Walk the list of monitors in the system.
(15) SDK: AsyncMonitorSystem::Count, etc.
LXxMETHOD( LxResult, Count) ( LXtObjectID self, int *count); LXxMETHOD( LxResult, ByIndex) ( LXtObjectID self, int index, void **ppvObj);
Empty AsyncMonitorSystem Python user class.
(16) PY: empty AsyncMonitorSystem user class
pass
Standard Dialog Service
The standard dialog service provides access to a standardize dialogs useful to plug-ins.
(17) SDK: LXa_STDDIALOGSERVICE, etc. defines
#define LXa_STDDIALOGSERVICE "stddialogservice" #define LXu_STDDIALOGSERVICE "A78FA063-6C8D-471f-8981-6BAEFF62BEE3"
(18) SDK: StdDialogService::ScriptQuery
LXxMETHOD( LxResult, ScriptQuery) ( LXtObjectID self, void **ppvObj);
Monitors
Clients can request an ILxMonitor, which can be used to create/open progress bar dialogs.
Prior to 701, only the first client to request a monitor will succeed, with the rest getting back LXe_NOTAVAILABLE. However, the system maintains a count of allocate/release calls, meaning that it is pivital that MonitorRelease() is called to release the monitor, rather than the client calling the monitor object's Release() method directly.
801 introduces support for sub-monitors. This means that allocating a monitor while another monitor is already running will now return a new monitor. Functionally, the two monitors are independent, but the sub-monitor can be considered to fill the current step in the parent monitor, although the sub-monitor will not affect the parent monitor in any way (meaning, you should still step the parent monitor even if the sub-monitor appears to fill that step in the UI). Note that it is still critical that the monitors be released with MonitorRelease() instead of calling the monitor object's Release() method directly.
(19) SDK: StdDialogService::MonitorAllocate, etc.
LXxMETHOD( LxResult, MonitorAllocate) ( LXtObjectID self, const char *title, void **ppvObj); LXxMETHOD( LxResult, MonitorRelease) ( LXtObjectID self);
(20) SDK: CLxUser_StdDialogService::MonitorAllocate method
bool MonitorAllocate ( const std::string &title, CLxLoc_Monitor &monitor) { LXtObjectID obj; LxResult rc; rc = CLxLoc_StdDialogService::MonitorAllocate (title.c_str (), &obj); if (LXx_FAIL (rc)) return false; return monitor.take (obj); }
Messages and Message Dialogs
Clients can request an ILxMessage. This can be used to open dialogs for user input, or pased to other clients that require them. These objects should be released as normal, via their Release() methods.
(21) SDK: StdDialogService::MessageAllocate
LXxMETHOD( LxResult, MessageAllocate) ( LXtObjectID self, void **ppvObj);
(22) SDK: CLxUser_StdDialogService::MessageAllocate method
bool MessageAllocate ( CLxLoc_Message &message) { LXtObjectID obj; LxResult rc; rc = CLxLoc_StdDialogService::MessageAllocate (&obj); if (LXx_FAIL (rc)) return false; return message.take (obj); }
An ILxMessage object can be displayed in a standard dialog. This dialog also features a help button if a help URL is provided. Lastly, a popup is available to the user that lets them decide how to handle the message in the future. Currently, the options are DIALOG and HIDDEN. If HIDDEN, the the dialog will not be displayed at all.
A title string is optional; it can contain a valid message string in the form "@table@message@", where message is either a dictionary lookup string or an integer ID code, or it can just be a simple string. The simple string method is not recommended unless it has already been translated. If the title is NULL, one will be generated based on the ILxMessageID's code.
The service can also be used to present the user with choice dialogs, such as OK/Cancel or Yes/No/Yes All/No All/Cancel. This kind of dialog is opened simply by using one of the following as the LxResult message code in place of a real info/warning/error code. Any other message code will result in a dialog with "OK" as the only button.
OKCANCEL | This is a typical binary dialog with OK and Cancel. |
YESNO | This is a slight varient of the binary dialog for answering questions: Yes, and No. |
YESNOCAN | This is a standard trinary dialog, which is like a binary dialog but with an extra "none of the above" option. The dismissal buttons are: Yes, No, and Cancel. |
SAVEOK | This trinary varient is intended for asking the user if they want to save an object which has been changed. It has three states: Save, Don't Save, and Cancel. |
YESNOALL | This dialog type has five states which are really just a two-by-two matrix of choices plus cancel. Intended for asking a question for a series of like questions, the buttons are: Yes, Yes to All, No, No to All, and Cancel. |
YESNOTOALL | This dialog type is similar to YESNOALL, but is missing the "Yes To All" option. The buttons are: Yes, No, No to All, and Cancel. |
YESTOALLCANCEL | Again similar to YESNOALL, but missing the No and No To All options. The buttons are: Yes, Yes to All, and Cancel. |
(23) SDK: LXeMSGDIALOG_AS_OKCANCEL, etc. defines
#define LXeMSGDIALOG_AS_OKCANCEL LXxGOODCODE( LXeSYS_COMP, 50 ) #define LXeMSGDIALOG_AS_YESNO LXxGOODCODE( LXeSYS_COMP, 51 ) #define LXeMSGDIALOG_AS_YESNOCANCEL LXxGOODCODE( LXeSYS_COMP, 52 ) #define LXeMSGDIALOG_AS_SAVEOK LXxGOODCODE( LXeSYS_COMP, 53 ) #define LXeMSGDIALOG_AS_YESNOALL LXxGOODCODE( LXeSYS_COMP, 54 ) #define LXeMSGDIALOG_AS_YESNOTOALL LXxGOODCODE( LXeSYS_COMP, 55 ) #define LXeMSGDIALOG_AS_YESTOALLCANCEL LXxGOODCODE( LXeSYS_COMP, 56 )
LXiMSGDIALOG_EMPTY is retruned if a string is present, but it contains only white space. LXiMSGDIALOG_INVALID is returned if there is a problem with the message object (e.g., it's NULL).
(24) SDK: LXeMSGDIALOG_EMPTY, etc. defines
#define LXeMSGDIALOG_EMPTY LXxFAILCODE( LXeSYS_COMP, 60 ) #define LXeMSGDIALOG_INVALID LXxFAILCODE( LXeSYS_COMP, 61 )
(25) SDK: StdDialogService::MessageOpen
LXxMETHOD( LxResult, MessageOpen) ( LXtObjectID self, LXtObjectID message, const char *title, const char *helpURL, const char *cookie);
If opened successfully as a question dialog, one of the following will be returned. If opened as an OK Only dialog (as in, not one of the LXeMSGDIALOG_AS codes), OK is always returned. No and Cancel are fail codes, while Yes, OK and Yes To All are good codes, which allows for some quick generalized checking with LXx_FAIL() and LXx_OK().
(26) SDK: LXeMSGDIALOG_OK, etc. defines
#define LXeMSGDIALOG_OK LXe_OK #define LXeMSGDIALOG_YES LXe_OK // Also for "Save" in the SAVEOK dialog #define LXeMSGDIALOG_YESTOALL LXxGOODCODE( LXeSYS_COMP, 70 ) #define LXeMSGDIALOG_NO LXxFAILCODE( LXeSYS_COMP, 71 ) // Also for "Don't Save" in the SAVEOK dialog #define LXeMSGDIALOG_NOTOALL LXxFAILCODE( LXeSYS_COMP, 72 ) #define LXeMSGDIALOG_CANCEL LXxFAILCODE( LXeSYS_COMP, 73 )
Clients can also create asynchronous monitors. These can be created as root-level monitors are as the only child of another asynchronous monitor. Aysnc monitors must be released with AsyncMonitorRelease() to ensure that they are disposed of properly. These monitors expose the normal ILxMonitor interface as well as an ILxAsyncMonitorInfo interface that can be used to read information out of the monitor.
Root-level monitors are associated with a system, which is usually related to the owner of the monitor (say, "presetBrowser" or "preview"). These are used to organize the monitors in the Activity View. The usernames for these systems are defined through configs by adding entries to the "asyncMonitorSystems" message table.
(27) SDK: Sync Monitor Username Example
<atom type="Messages"> <hash type="Table" key="asyncMonitorSystems.en_US"> <hash type="T" key="presetBrowser">Preset Browser</hash> <hash type="T" key="prevew">Preview</hash> </hash> </atom>
Asynchronous Monitors
Calling the MonitorAllocate() from a thread will implicitly create an async monitor with an empty system string for that thread. Such monitors should be released with MonitorRelease() as normal, although they are considered to be async monitors.
(28) SDK: StdDialogService::AsyncMonitorAllocate, etc.
LXxMETHOD( LxResult, AsyncMonitorAllocate) ( LXtObjectID self, const char *system, const char *title, void **ppvObj); LXxMETHOD( LxResult, AsyncMonitorSubAllocate) ( LXtObjectID self, LXtObjectID parent, const char *title, void **ppvObj); LXxMETHOD( LxResult, AsyncMonitorRelease) ( LXtObjectID self, LXtObjectID monitor);
(29) SDK: CLxUser_StdDialogService::AsyncMonitorAllocate method
bool AsyncMonitorAllocate ( const std::string &system, const std::string &title, CLxLoc_Monitor &monitor) { LXtObjectID obj; LxResult rc; rc = CLxLoc_StdDialogService::AsyncMonitorAllocate (system.c_str (), title.c_str (), &obj); if (LXx_FAIL (rc)) return false; return monitor.take (obj); } bool AsyncMonitorSubAllocate ( LXtObjectID parent, const std::string &title, CLxLoc_Monitor &monitor) { LXtObjectID obj; LxResult rc; rc = CLxLoc_StdDialogService::AsyncMonitorSubAllocate ((ILxUnknownID)parent, title.c_str (), &obj); if (LXx_FAIL (rc)) return false; return monitor.take (obj); }
These can be used to walk the list of async monitor systems or look them up by name. Objects returned by these methods sport an ILxAsyncMonitorSystem interface, and must be released as normal when no longer needed. These methods should only be called from the main thread.
Lookup a system by its name.
(30) SDK: StdDialogService::AsyncMonitorSystemCount, etc.
LXxMETHOD( LxResult, AsyncMonitorSystemCount) ( LXtObjectID self, int *count); LXxMETHOD( LxResult, AsyncMonitorSystemByIndex) ( LXtObjectID self, int index, void **ppvObj); LXxMETHOD( LxResult, AsyncMonitorSystemLookup) ( LXtObjectID self, const char *name, void **ppvObj);
This can be used to look up an async monitor by its unique identifier string. As always, the returned object must be released when no longer needed.
(31) SDK: StdDialogService::AsyncMonitorLookup
LXxMETHOD( LxResult, AsyncMonitorLookup) ( LXtObjectID self, const char *ident, void **ppvObj);
File Dialogs
This service method will display any of several types of file dialogs to allow the user to browse to a location, file or list of files. The configuration of the dilaog is defined by the client's dialog object.
(32) SDK: StdDialogService::FileDialog
LXxMETHOD( LxResult, FileDialog) ( LXtObjectID self, LXtObjectID dlgObj);
This returns LXeMSGDIALOG_OK or CANCEL for normal operation, or some special error code for other problems.
(33) SDK: LXeFILEDIALOG_BADCLASS, etc. defines
#define LXeFILEDIALOG_BADCLASS LXxFAILCODE( LXeSYS_COMP, 80 ) #define LXeFILEDIALOG_BADFORMAT LXxFAILCODE( LXeSYS_COMP, 81 )
The Flags() method returns flag bits to determine the behavior of the dialog.
LOAD | By default the dialog will be for loading exising files. |
SAVE | This flag changes the dialog to allow it to create new files. This makes the format important. |
DIRECTORY | This flag changes the dialog to browse for a directory. It's mutually exclusive with the SAVE flag. |
MULTIPLE | For load dialogs this allows the user to pick more than one file. |
OVERWRITE | Allow overwrite for save dialogs. |
NOFORMATS | Suppress the format choice. |
(34) SDK: FileDialogClient::Flags
LXxMETHOD( unsigned, Flags) ( LXtObjectID self);
(35) SDK: LXfFILEDIALOG_LOAD, etc. defines
#define LXfFILEDIALOG_LOAD 0x00 #define LXfFILEDIALOG_SAVE 0x01 #define LXfFILEDIALOG_DIRECTORY 0x02 #define LXfFILEDIALOG_MULTIPLE 0x04 #define LXfFILEDIALOG_OVERWRITE 0x08 #define LXfFILEDIALOG_NOFORMATS 0x10
The client provides the title of the dialog through a message object.
(36) SDK: FileDialogClient::Title
LXxMETHOD( LxResult, Title) ( LXtObjectID self, LXtObjectID message);
The class is the type of file object that you want to load or save, and is required for all file dialogs. Common choices are LXa_SCENE and LXa_IMAGE. If you have defined a custom type through the config you can also give that here.
(37) SDK: FileDialogClient::FileClass
LXxMETHOD( const char *, FileClass) ( LXtObjectID self);
The context string is an optional string which just provides a way for the system to remember the path for this dialog. By providing a unique context string the same dialog opened again will go back to the last place the user was looking. This is useful for common types like images because you don't want to override all stored image paths, but not so important for custom types.
(38) SDK: FileDialogClient::ContextString
LXxMETHOD( LxResult, ContextString) ( LXtObjectID self, const char **context);
This method returns the initial format for the dialog. The format must match the object class, so it has to be an image format for images or a scene format for scenes, etc. If missing the format will default to the first one for this class, and is only needed if there is more than one.
(39) SDK: FileDialogClient::FileFormat
LXxMETHOD( LxResult, FileFormat) ( LXtObjectID self, const char **format);
This returns the initial path for the dialog. A full path can be returned for load and directory dialogs, or just a base name for loading and saving. If missing the file name field will be empty.
(40) SDK: FileDialogClient::StartPath
LXxMETHOD( LxResult, StartPath) ( LXtObjectID self, const char **filepath);
Results are returned by calling methods on the client object. This is called for each file or path chosen by the user.
(41) SDK: FileDialogClient::ResultPath
LXxMETHOD( LxResult, ResultPath) ( LXtObjectID self, const char *filepath);
For save dialogs this method is called to indicate the format that was chosen. For object classes with multiple formats this should be stored and passed back as the starting format if the dialog is opened again.
(42) SDK: FileDialogClient::ResultFormat
LXxMETHOD( LxResult, ResultFormat) ( LXtObjectID self, const char *format);
(43) SDK: LXu_FILEDIALOGCLIENT define
#define LXu_FILEDIALOGCLIENT "77F97D4C-8AF9-4E3A-AA58-E8418990FCA8"
Nexus 11.1
In some cases async monitors are not abortable, and should not draw an abort widget in the activity view. This is purely cosmetic, and does not affect the operation of the moonitor, and thus is only available for root-level monitors, which are the ones that determine how the montior is displayed.
(44) SDK: StdDialogService::AsyncMonitorAllocateWithoutAbort
LXxMETHOD( LxResult, AsyncMonitorAllocateWithoutAbort) ( LXtObjectID self, const char *system, const char *title, void **ppvObj);
(45) SDK: CLxUser_StdDialogService::AsyncMonitorAllocateWithoutAbort method
bool AsyncMonitorAllocateWithoutAbort ( const std::string &system, const std::string &title, CLxLoc_Monitor &monitor) { LXtObjectID obj; LxResult rc; rc = CLxLoc_StdDialogService::AsyncMonitorAllocateWithoutAbort (system.c_str (), title.c_str (), &obj); if (LXx_FAIL (rc)) return false; return monitor.take (obj); }
Empty StdDialog service Python user class.
(46) PY: empty Service.StdDialog user class
pass