Hello World - Media Center Dialogs

  • Article

The Media Center API has a function to displays dialogs, similar to the ones Media Center uses itself.  An HTML application can take advantage of these to ask the user a question, or simply display a notification.  Here's a simple example of how to create one:

 <HTML>
<BODY BGColor="#0121BA">
<SCRIPT>

     function IsMCEEnabled()
    {
        return true
    }
    
    var MCE, Message, Caption, Timeout, Buttons, Modal, ReturnValue
    MCE = window.external.MediaCenter();
    Caption = "Hello World";
    Message = "This is a Media Center Dialog";
    Timeout = 10;
    Buttons = 1;
    Modal = true;

     ReturnValue = MCE.Dialog(Message, Caption, Buttons, Timeout, Modal);
</SCRIPT>
</BODY> 
</HTML>

Lets take a look at what this does.  First I've implemented a function called IsMCEEnabled, this lets Media Center know that the page was designed for Media Center.  Next I've declared the variables I'll be using to create my dialog and finally I've created the dialog itself.  The usage of most of the parameters in the Dialog function are obvious, but some need a little bit of explanation.  "Buttons" is a number that corresponds to the buttons to be displayed on the dialog in the following way:

Value Button
1 OK button
2 Cancel button
4 Yes button
8 No button

Combining the values allows you to specify multiple buttons, for example if "Buttons" had a value of 3 then an OK button and a Cancel Button would be created on the dialog, 5 would put an OK button and a Yes button on the dialog. 

"Timeout" is a value in seconds that the dialog is displayed for, in this case ten seconds.  Setting the value to 0 will display a modal dialog until it's dismissed by the user, for a non-modal (also called modeless and semi-modal) dialog it will disappear five seconds.  Whether a dialog is modal (center of the display and blocks access to the page behind it and prevents and navigation) or non-modal (appears at the bottom of the display and doesn't prevent access to the page or navigation) is controlled by a boolean which in this case I've named "Modal" - true creates a modal dialog and false a non-modal dialog.

Finally there's the return value of the Dialog function - this lets the page know what button a user pressed on the dialog, or if the dialog closed as a result of the timeout - note this only applies to modal dialogs, non-modal dialogs always return the same value because they are displayed asynchronously - so the return value will be created while the dialog is still on the screen, for this reason non-modal dialogs are best used for notification purposes.  Modal dialogs on the other hand block further script execution on the page until the user responds to them or the timeout occurs.  The return values fall into the following categories:

Value Action
0 OK button was pushed
1 Cancel button was pushed
2 Yes button was pushed
3 No button was pushed
5 The dialog closed due to the timeout
6 Dialog displayed (non-modal dialogs)

That's all there is to it!