stddialog (lx_stddialog.hpp)

From The Foundry MODO SDK wiki
(Redirected from ILxAsyncMonitorInfo (index))
Jump to: navigation, search
There are security restrictions on this page


Contents

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: Declarations
 #define LXu_ASYNCMONITORINFO            "adf5bb35-7180-4d6e-9348-49206ae7e6ca"
 #define LXa_ASYNCMONITORINFO            "asyncmonitorinfo"

Get the system and title of the monitor.

(2) SDK: ILxAsyncMonitorInfo interface
         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: ILxAsyncMonitorInfo interface
         LXxMETHOD(  LxResult,
 Progress) (
         LXtObjectID               self,
         double                  **progress);

This is similar, but takes into account sub-monitors to provide an overall progress value.

(4) SDK: ILxAsyncMonitorInfo interface
         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: ILxAsyncMonitorInfo interface
         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: ILxAsyncMonitorInfo interface
         LXxMETHOD(  LxResult,
 Identifier) (
         LXtObjectID               self,
         const char              **ident);

Tell the monitor to abort. This simply sets the abort flag, which is returned by IsAborted() and ILxMonitor::Step().

(7) SDK: ILxAsyncMonitorInfo interface
         LXxMETHOD(  LxResult,
 Abort) (
         LXtObjectID               self);

This returns LXe_TRUE if aborted, and LXe_FALSE if it is still running.

(8) SDK: ILxAsyncMonitorInfo interface
         LXxMETHOD(  LxResult,
 IsAborted) (
         LXtObjectID               self);

Empty AsyncMonitorInfo Python user class.

(9) PY: AsyncMonitorInfo method
 pass

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.

(10) SDK: Declarations
 #define LXu_ASYNCMONITORSYSTEM          "c573842a-d4fd-48eb-8fb0-078a721e5e0f"
 #define LXa_ASYNCMONITORSYSTEM          "asyncmonitorsystem"

Get the name of the system.

(11) SDK: ILxAsyncMonitorSystem interface
         LXxMETHOD(  LxResult,
 Name) (
         LXtObjectID               self,
         const char              **name);

Walk the list of monitors in the system.

(12) SDK: ILxAsyncMonitorSystem interface
         LXxMETHOD(  LxResult,
 Count) (
         LXtObjectID               self,
         int                      *count);
 
         LXxMETHOD(  LxResult,
 ByIndex) (
         LXtObjectID               self,
         int                       index,
         void                    **ppvObj);

Empty AsyncMonitorSystem Python user class.

(13) PY: AsyncMonitorSystem method
 pass

Standard Dialog Service

The standard dialog service provides access to a standardize dialogs useful to plug-ins.

(14) SDK: Declarations
 #define LXa_STDDIALOGSERVICE    "stddialogservice"
 #define LXu_STDDIALOGSERVICE    "A78FA063-6C8D-471f-8981-6BAEFF62BEE3"

(15) SDK: ILxStdDialogService interface
         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.

(16) SDK: ILxStdDialogService interface
         LXxMETHOD(  LxResult,
 MonitorAllocate) (
         LXtObjectID               self,
         const char               *title,
         void                    **ppvObj);
 
         LXxMETHOD(  LxResult,
 MonitorRelease) (
         LXtObjectID               self);

(17) User Service Class: StdDialogService 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.

(18) SDK: ILxStdDialogService interface
         LXxMETHOD(  LxResult,
 MessageAllocate) (
         LXtObjectID               self,
         void                    **ppvObj);

(19) User Service Class: StdDialogService 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.

(20) SDK: Declarations

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).

(21) SDK: Declarations

(22) SDK: ILxStdDialogService interface
         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().

(23) SDK: Declarations
 #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.

(24) 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.

(25) SDK: ILxStdDialogService interface
         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);

(26) User Service Class: StdDialogService 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.

(27) SDK: ILxStdDialogService interface
         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.

(28) SDK: ILxStdDialogService interface
         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.

(29) SDK: ILxStdDialogService interface
         LXxMETHOD(  LxResult,
 FileDialog) (
         LXtObjectID              self,
         LXtObjectID              dlgObj);

This returns LXeMSGDIALOG_OK or CANCEL for normal operation, or some special error code for other problems.

(30) SDK: Declarations

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.

(31) SDK: ILxFileDialogClient interface
         LXxMETHOD(  unsigned,
 Flags) (
         LXtObjectID              self);

(32) SDK: Declarations

The client provides the title of the dialog through a message object.

(33) SDK: ILxFileDialogClient interface
         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.

(34) SDK: ILxFileDialogClient interface
         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.

(35) SDK: ILxFileDialogClient interface
         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.

(36) SDK: ILxFileDialogClient interface
         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.

(37) SDK: ILxFileDialogClient interface
         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.

(38) SDK: ILxFileDialogClient interface
         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.

(39) SDK: ILxFileDialogClient interface
         LXxMETHOD(  LxResult,
 ResultFormat) (
         LXtObjectID              self,
         const char              *format);

(40) SDK: Declarations
 #define LXu_FILEDIALOGCLIENT            "77F97D4C-8AF9-4E3A-AA58-E8418990FCA8"

Empty StdDialog service Python user class.

(41) PY: StdDialogService method
 pass