Difference between revisions of "IC Python API:Message Box"

From Reallusion Wiki!
Jump to: navigation, search
m (→‎Available Buttons)
m
 
(11 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
{{TOC}}
 
{{TOC}}
−
{{Parent|IC_Python_API:RL_Python_Samples|RL Python Samples}}
+
{{Parent|IC_Python_API#Python_Samples|RL Python Samples}}
  
 
iClone Python API has the ability to display pop-up message boxes that can ease the flow of your scripted procedures, as well as provide warnings and alerts.  Message boxes can be sparse with no interaction except for the universal close window button on the top right of the window bar.  They can also support a single checkbox and a single button interaction.
 
iClone Python API has the ability to display pop-up message boxes that can ease the flow of your scripted procedures, as well as provide warnings and alerts.  Message boxes can be sparse with no interaction except for the universal close window button on the top right of the window bar.  They can also support a single checkbox and a single button interaction.
Line 11: Line 11:
 
!Python Enum
 
!Python Enum
 
!Button Label
 
!Button Label
−
!Value on Press
+
!Return Value
 
!Bit Integer
 
!Bit Integer
 
|-
 
|-
Line 76: Line 76:
 
|RLPy.EMsgButton_Close
 
|RLPy.EMsgButton_Close
 
|"Close"
 
|"Close"
−
|2097152
 
−
|21-bit (2^21)
 
−
|-
 
−
|Dialog Exited
 
−
| --
 
 
|2097152
 
|2097152
 
|21-bit (2^21)
 
|21-bit (2^21)
Line 108: Line 103:
 
|67108864
 
|67108864
 
|26-bit (2^26)
 
|26-bit (2^26)
 +
|}
 +
 +
=== Non-Button Enumerations ===
 +
 +
The following are part of the EmsgButton enumerations but can't be used to create a dialog window.
 +
 +
{|class = "wikitable"
 +
!Python Enum / User Action
 +
!UI Representation
 +
!Return Value
 +
!Bit Integer
 +
|-
 +
|Dialog Exited
 +
|Exit Button
 +
|2097152
 +
|21-bit (2^21)
 
|-
 
|-
−
| --
+
|RLPY.EMsgButton_RestoreDefaults
−
| --
+
|None
 
|134217728
 
|134217728
 
|27-bit (2^27)
 
|27-bit (2^27)
 
|-
 
|-
−
|Check Box Activated
+
|Checkbox Activation<br>RLPy.EMsgButton_OkDontAskAgain
−
|(Check Box)
+
|Check Box
 
|268435456
 
|268435456
 
|28-bit (2^28)
 
|28-bit (2^28)
 
|}
 
|}
  
−
== Required Modules ==
+
== Necessary Modules ==
  
 
The only required module for this lesson is the standard Reallusion Python API library.
 
The only required module for this lesson is the standard Reallusion Python API library.
Line 129: Line 140:
  
 
== Simple Message Box ==
 
== Simple Message Box ==
 +
 +
[[File:Ic_python_api_message_box_01.png|right]]
  
 
The most simple message boxes just provide additional information to the user.
 
The most simple message boxes just provide additional information to the user.
Line 140: Line 153:
  
 
== Message Box with Checkbox ==
 
== Message Box with Checkbox ==
 +
 +
[[File:Ic_python_api_message_box_02.png|right]]
  
 
In addition, message boxes can support check-boxes for more complex interactions.
 
In addition, message boxes can support check-boxes for more complex interactions.
Line 154: Line 169:
  
 
== Action Blocking Message Boxes ==
 
== Action Blocking Message Boxes ==
 +
 +
[[File: Ic_python_api_message_box_03.png|right]]
  
 
Message boxes are asynchronous; they block the next action until the user removes it by clicking on the button or exiting the window.
 
Message boxes are asynchronous; they block the next action until the user removes it by clicking on the button or exiting the window.
Line 160: Line 177:
 
RLPy.RUi.ShowMessageBox(
 
RLPy.RUi.ShowMessageBox(
 
     "Message 3/3",
 
     "Message 3/3",
−
     {1024: "<b>False:</b> Checkbox was <b><i>NOT</i></b> activated.",
+
     {RLPy.EMsgButton_Ok: "<b>False:</b> Checkbox was <b><i>NOT</i></b> activated.",
−
     268435456: "<b>True</b> Checkbox was activated!",
+
     RLPy.EMsgButton_OkDontAskAgain: "<b>True</b> Checkbox was activated!",
−
     2097152: "<b>Canceled:</b> The message box was closed prematurely.",
+
     RLPy.EMsgButton_Close: "<b>Canceled:</b> The message box was closed prematurely.",
 
     }[button_status],
 
     }[button_status],
 
     RLPy.EMsgButton_Ok
 
     RLPy.EMsgButton_Ok
Line 168: Line 185:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
== Everything Put Together ==
+
== Adding More Buttons ==
  
−
You can copy and paste the following code into a PY file and load it into iClone via '''Script > Load Python'''.  
+
[[File: Ic_python_api_message_box_04.png|right]]
 +
 
 +
You add more buttons by adding more enumerations separated by "|".  
  
 
<syntaxhighlight lang="python">
 
<syntaxhighlight lang="python">
−
import RLPy
 
−
 
 
RLPy.RUi.ShowMessageBox(
 
RLPy.RUi.ShowMessageBox(
−
     "Message 1/3",
+
     "Ok and Cancel",
−
     "Message boxes can block operations.",
+
     "You can add more buttons.",
−
     RLPy.EMsgButton_Ok)
+
     RLPy.EMsgButton_Ok | RLPy.EMsgButton_Cancel
−
 
+
−
button_status = RLPy.RUi.ShowMessageBox(
+
−
    "Message 2/3",
+
−
    "We can demonstrate this with a check-box...",
+
−
    RLPy.EMsgButton_Close,
+
−
    True,
+
−
    "Try me!"
+
−
)
+
−
 
+
−
RLPy.RUi.ShowMessageBox(
+
−
    "Message 3/3",
+
−
    {1024: "<b>False:</b> Checkbox was <b><i>NOT</i></b> activated.",
+
−
    268435456: "<b>True</b> Checkbox was activated!",
+
−
    2097152: "<b>Canceled:</b> The message box was closed prematurely.",
+
−
    }[button_status],
+
−
    RLPy.EMsgButton_Ok
+
 
)
 
)
 
</syntaxhighlight>
 
</syntaxhighlight>

Latest revision as of 21:59, 19 October 2020

Main article: RL Python Samples.

iClone Python API has the ability to display pop-up message boxes that can ease the flow of your scripted procedures, as well as provide warnings and alerts. Message boxes can be sparse with no interaction except for the universal close window button on the top right of the window bar. They can also support a single checkbox and a single button interaction.

Available Buttons

The label on the single button changes according to the type of button called, they are the following:

Python Enum Button Label Return Value Bit Integer
RLPy.EMsgButton_NoButton "OK" 0 0-bit (2^0)
RLPy.EMsgButton_Ok "OK" 1024 10-bit (2^10)
RLPy.EMsgButton_Save "Save" 2048 11-bit (2^11)
RLPy.EMsgButton_SaveAll "Save All" 4096 12-bit (2^12)
RLPy.EMsgButton_Open "Open" 8196 13-bit (2^13)
RLPy.EMsgButton_Yes "Yes" 16384 14-bit (2^14)
RLPy.EMsgButton_YesToAll "Yes to All" 32768 15-bit (2^15)
RLPy.EMsgButton_No "No" 65536 16-bit (2^16)
RLPy.EMsgButton_NoToAll "No to All" 131072 17-bit (2^17)
RLPy.EMsgButton_Abort "Abort" 262144 18-bit (2^18)
RLPy.EMsgButton_Retry "Retry" 524288 19-bit (2^19)
RLPy.EMsgButton_Overlook "Ignore" 1048576 20-bit (2^20)
RLPy.EMsgButton_Close "Close" 2097152 21-bit (2^21)
RLPy.EMsgButton_Cancel "Cancel" 4194304 22-bit (2^22)
RLPy.EMsgButton_Discard "Discard" 8388608 23-bit (2^23)
RLPy.EMsgButton_Help "Help" 16777216 24-bit (2^24)
RLPy.EMsgButton_Apply "Apply" 33554432 25-bit (2^25)
RLPy.EMsgButton_Reset "Reset" 67108864 26-bit (2^26)

Non-Button Enumerations

The following are part of the EmsgButton enumerations but can't be used to create a dialog window.

Python Enum / User Action UI Representation Return Value Bit Integer
Dialog Exited Exit Button 2097152 21-bit (2^21)
RLPY.EMsgButton_RestoreDefaults None 134217728 27-bit (2^27)
Checkbox Activation
RLPy.EMsgButton_OkDontAskAgain 		Check Box 268435456 28-bit (2^28)

Necessary Modules

The only required module for this lesson is the standard Reallusion Python API library. 

import RLPy

Simple Message Box

Ic python api message box 01.png

The most simple message boxes just provide additional information to the user. 

RLPy.RUi.ShowMessageBox(
    "Message 1/3",
    "Message boxes can block operations.",
    RLPy.EMsgButton_Ok)

Message Box with Checkbox

Ic python api message box 02.png

In addition, message boxes can support check-boxes for more complex interactions. 

button_status = RLPy.RUi.ShowMessageBox(
    "Message 2/3",
    "We can demonstrate this with a check-box...",
    RLPy.EMsgButton_Close,
    True,
    "Try me!"
)

Action Blocking Message Boxes

Ic python api message box 03.png

Message boxes are asynchronous; they block the next action until the user removes it by clicking on the button or exiting the window. 

RLPy.RUi.ShowMessageBox(
    "Message 3/3",
    {RLPy.EMsgButton_Ok: "<b>False:</b> Checkbox was <b><i>NOT</i></b> activated.",
     RLPy.EMsgButton_OkDontAskAgain: "<b>True</b> Checkbox was activated!",
     RLPy.EMsgButton_Close: "<b>Canceled:</b> The message box was closed prematurely.",
     }[button_status],
    RLPy.EMsgButton_Ok
)

Adding More Buttons

Ic python api message box 04.png

You add more buttons by adding more enumerations separated by "|". 

RLPy.RUi.ShowMessageBox(
    "Ok and Cancel",
    "You can add more buttons.",
    RLPy.EMsgButton_Ok | RLPy.EMsgButton_Cancel
)

APIs Used

You can research the following references for the APIs deployed in this code.

Retrieved from "https://wiki.reallusion.com/index.php?title=IC_Python_API:Message_Box&oldid=4811"