stddialog (lx_stddialog.hpp)

There are security restrictions on this page

         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