Stddialog

ILxAsyncMonitorInfo

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

Public Functions

LxResult System(LXtObjectID self, const char **system)

Get the system and title of the monitor.

LxResult Title(LXtObjectID self, const char **title)

LxResult Progress(LXtObjectID self, double *progress)

Get the current progress of this single monitor, ignoring child monitors.

LxResult OverallProgress(LXtObjectID self, double *progress)

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

LxResult Parent(LXtObjectID self, void **ppvObj)

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.

LxResult Child(LXtObjectID self, void **ppvObj)

LxResult Identifier(LXtObjectID self, const char **ident)

This returns a unique identifier string for the monitor, mostly to make it easier to address from things like the Activity View commands.

LxResult CanAbort(LXtObjectID self)

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.

LxResult Abort(LXtObjectID self)

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

LxResult IsAborted(LXtObjectID self)

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

ILxAsyncMonitorInfo1

class ILxAsyncMonitorInfo1

This interface was retired in modo 11.1, and was replaced with an updated one that adds the CanAbort() method.

Public Functions

LxResult System(LXtObjectID self, const char **system)

LxResult Title(LXtObjectID self, const char **title)

LxResult Progress(LXtObjectID self, double *progress)

LxResult OverallProgress(LXtObjectID self, double *progress)

LxResult Parent(LXtObjectID self, void **ppvObj)

LxResult Child(LXtObjectID self, void **ppvObj)

LxResult Identifier(LXtObjectID self, const char **ident)

LxResult Abort(LXtObjectID self)

LxResult IsAborted(LXtObjectID self)

ILxAsyncMonitorSystem

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

Public Functions

LxResult Name(LXtObjectID self, const char **name)

Get the name of the system.

LxResult Count(LXtObjectID self, int *count)

Walk the list of monitors in the system.

LxResult ByIndex(LXtObjectID self, int index, void **ppvObj)

ILxColorDialog

class ILxColorDialog

The color dialog can be replaced with an arbitrary one defined by a plug-in. ILxColorDialog is very simple, and includes a single method, DoDialog().

Public Functions

LxResult DoDialog(LXtObjectID self, const char *title, double stops, double gamma, double *rgb)

DoDialog is responsible for opening a color dialog. All dialog handling is up to the server. This includes whatever methods it chooses to create and display the dialog, handling windowing and event loops, etc. The rgb[] argument is initialized to the original color, and is also used to return any color the user may have chosen. This color may be HDR (i.e., outside the range of 0-1). The title string is a pre-translated string to be displayed in the dialog’s title bar. The method should return an LXe_OK() code if the user choose a color, an LXe_FAIL() code on an error, or LXe_ABORT if the user canceled the dialog. The current stops are also provided for displaying HDR colors, and are applied by multiplying or dividing by two to the power of the stops (i.e., pow(2,stops)) to convert between HDR and LDR. Stops should always be applied before gamma. The gamma value is used to gamma correct the colors shown in the color dialog to match those in modo. This may be 1.0 if no correction should be applied. Gamma can be applied by raising a color’s RGB values to the gamma value (i.e., pow(rgb[x],gamma)). Gamma should always be applied after stops. The returned RGB value should not be gamma corrected, but can be HDR.

ILxStdDialogService

class ILxStdDialogService

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

Public Functions

LxResult ScriptQuery(LXtObjectID self, void **ppvObj)

LxResult MonitorAllocate(LXtObjectID self, const char *title, void **ppvObj)

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.

LxResult MonitorRelease(LXtObjectID self)

LxResult MessageAllocate(LXtObjectID self, void **ppvObj)

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.

LxResult MessageOpen(LXtObjectID self, LXtObjectID message, const char *title, const char *helpURL, const char *cookie)

LxResult AsyncMonitorAllocate(LXtObjectID self, const char *system, const char *title, void **ppvObj)

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.

LxResult AsyncMonitorSubAllocate(LXtObjectID self, LXtObjectID parent, const char *title, void **ppvObj)

LxResult AsyncMonitorRelease(LXtObjectID self, LXtObjectID monitor)

LxResult AsyncMonitorSystemCount(LXtObjectID self, int *count)

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.

LxResult AsyncMonitorSystemByIndex(LXtObjectID self, int index, void **ppvObj)

LxResult AsyncMonitorSystemLookup(LXtObjectID self, const char *name, void **ppvObj)

LxResult AsyncMonitorLookup(LXtObjectID self, const char *ident, 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.

LxResult FileDialog(LXtObjectID self, LXtObjectID dlgObj)

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.

LxResult AsyncMonitorAllocateWithoutAbort(LXtObjectID self, const char *system, const char *title, void **ppvObj)

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.

LxResult MonitorReleaseObj(LXtObjectID self, LXtObjectID monitor)

Clients are supposed to call AllocateMonitor() / MonitorRelease() in nested pairs to bracket regions of code being monitored. In cases where that’s not always possible (such as with the Python Monitor object implementation) this version takes the actual object being released and removes it from the stack or is harmless if it’s already been removed indirectly.

bool MonitorAllocate(const std::string &title, CLxLoc_Monitor &monitor)

User Class Only:

bool MessageAllocate(CLxLoc_Message &message)

User Class Only:

bool AsyncMonitorAllocate(const std::string &system, const std::string &title, CLxLoc_Monitor &monitor)

User Class Only:

bool AsyncMonitorSubAllocate(LXtObjectID parent, const std::string &title, CLxLoc_Monitor &monitor)

bool AsyncMonitorAllocateWithoutAbort(const std::string &system, const std::string &title, CLxLoc_Monitor &monitor)

User Class Only:

---

LXeMSGDIALOG_AS_OKCANCEL

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

• LXeMSGDIALOG_AS_YESNO

• LXeMSGDIALOG_AS_YESNOCANCEL

• LXeMSGDIALOG_AS_SAVEOK

• LXeMSGDIALOG_AS_YESNOALL

• LXeMSGDIALOG_AS_YESNOTOALL

• LXeMSGDIALOG_AS_YESTOALLCANCEL

---

LXeMSGDIALOG_EMPTY

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

• LXeMSGDIALOG_INVALID

---

LXeMSGDIALOG_OK

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

• LXeMSGDIALOG_YES

• LXeMSGDIALOG_YESTOALL

• LXeMSGDIALOG_NO

• LXeMSGDIALOG_NOTOALL

• LXeMSGDIALOG_CANCEL

---

LXeFILEDIALOG_BADCLASS

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

• LXeFILEDIALOG_BADFORMAT

ILxFileDialogClient

class ILxFileDialogClient

Public Functions

unsigned Flags(LXtObjectID self)

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.

LxResult Title(LXtObjectID self, LXtObjectID message)

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

const char *FileClass(LXtObjectID self)

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.

LxResult ContextString(LXtObjectID self, const char **context)

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.

LxResult FileFormat(LXtObjectID self, const char **format)

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.

LxResult StartPath(LXtObjectID self, const char **filepath)

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.

LxResult ResultPath(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.

LxResult ResultFormat(LXtObjectID self, const char *format)

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.

• LXfFILEDIALOG_LOAD

• LXfFILEDIALOG_SAVE

• LXfFILEDIALOG_DIRECTORY

• LXfFILEDIALOG_MULTIPLE

• LXfFILEDIALOG_OVERWRITE

• LXfFILEDIALOG_NOFORMATS