4umi.com/web/javascript/shell

Pop the shell

Useful Javascript

The Windows shell goes wild. An ActiveXObject assigned to the WScript.Shell object, provides access to some very useful core os components indeed. ActiveXObjects are notoriously shy and eluding, they prefer to operate in the background and their actions may not always be immediately seen, such as when reading local files, but the Popup() method is unmistakable and unavoidable.

Use this to display customized alert-type dialogs, with ‘Yes’ and ‘No’ buttons, and a variety of icons. There is even the option to have the dialog window time out automatically and disappear without user action, and resume script from there.

The grammar

Description : Displays a modeless dialog, with features

Syntax :

returnvalue = obj.Popup( text, timeout, title, features );

Where :

VariableDescriptionTypeWorthDefault value
returnvalueThe button clicked by the user's reply.Numbern/a-1
objThe shell object.ObjectRequiredn/a
textThe message.StringRequired''
timeoutThe number of seconds after which the popup self-closes.NumberOptional0
titleThe text in the title bar.StringOptionalWindows Script Host
featuresSpecification of buttons and icon.NumberOptional0

Note :

A modal window is one that blocks user interaction with the originating window until it is dismissed, such in contrast to modeless dialogs that do not prevent scrolling and text selections in the main window. Other windows, even if running the same application, remain normally accessible.

Ordinary alert and confirm boxes accept Unicode escaped characters (like alert( '\u20ac for euro' ) ) within the message text generally, but the character set in popups from the shell seems more limited. Experiments suggest entering symbols directly gives the best chance of the characters displaying correctly in the popup window. A test is undertaken below.

The timeout period should be taken with a great margin for inaccuracy. If omitted or 0 (zero), it can wait forever.

Although the features have no distinct effect on the type of return value, to the end user the type of the dialog window is a very important aspect of the communication. To differentiate between types, there is a choice of a six groups of buttons, and four icons. The values for both, as listed in the appendix below, are simply added together and the resulting number is passed as the argument. Each icon is usually associated with a sound clip on the local machine to finish off the experience.

No further customization is possible.

An illustration

There are four types of iconography available. The illustrations displayed below have been shot in Windows ME.

 Critical icon.  Question icon.  Exclamation icon.  Information icon.

A demonstration

Enter a line of text to pop up, then click ‘Go’ to pop up your very own and unique ActiveX Shell Popup. The code will be written in a field below the form.

Settings
   
Your code
  1. // Ready...

The script

The function runs on submission of the form, which passes itself as the parameter. First it assembles the code as specified by the user, and writes it to the output area. Next the shell is called into being (stored in variable o), and it is immediately put to use by calling its Popup() method on line 9.

The value to use for the buttons is read directly from the selectedIndex property of the <select> element. This is possible because the button values form a neat zero based range. The value for the icon must be taken from the value attribute of the selected <option>, which is converted to an integer with the extra + before adding the two up on line 6.

The user replies and the returnvalue (variable p) is tossed in a switch statement, with branches for each of possible buttons clicked. They should be able to speak for themselves. (A version which uses an if/else construction to the same effect can be found near the bottom of this page's source.) More useful actions then these example messages and a return statement to another function are, well, thinkable.

As we are using ActiveXObjects, we have limited ourselves to a sure ie only audience, and can safely employ the non-standard quick and dirty shortcut innerHTML property of a fieldset to contain the resulting code, highlighted by a function called hilitejs. Finally, the calls to function ask() show how the object o can be passed to other scopes than the one in which it was created, and so behave just like other variables.

function popup( f ) {
 var el = f.elements, o, p, 
  text = el.tex.value,
  time = +el.tim.value,
  title= el.tit.value,
  type = el.but.selectedIndex + ( +el.ico.options[ el.ico.selectedIndex ].value );
 try {
  o = new ActiveXObject( 'WScript.Shell' );
  p = o.Popup( text, time, title, type );
  switch( p ) {
   case -1: window.status = 'Timed out at ' + Date();
    break;
   case 1: window.alert( 'Well, OK then.' );
    break;
   case 2: /* window.alert( 'Canceled.' ); */
    break;
   case 3: while(--p) { window.alert( 'You aborted the popup!' ); }
    break;
   case 4: window.alert( 'Let \'s try again...' ); popup( f );
    break;
   case 5: o.Popup( 'You may ignore this too.', 0, '' );
    break;
   case 6: o.Popup( ask( o, 'Yes?' )===p ? 'Yes, of course!' : 'Ah.' );
    break;
   case 7:
    if( ask( o, 'No?' )===p ) { 
     document.write( '<h1>No!<\/h1>'.big() +
      'Back to the shell'.link( 'javascript:history.go(-1);' ) + '.'
     );
    }else{
     window.alert( secretmessage );
    }
    break;
   default:  //  should not occur, we have cases for all returnvalues
    window.alert( 'The popup returned a value of ' + p + '.' );
  }
 gid( 'ol' ).innerHTML = toli( hilitejs(
  'var reply = new ActiveXObject( \'WScript.Shell\' ).Popup(\n  ' +
   [ esc( text ), time, esc( title ), type ].join( ',\n  ' ) + '\n);'
  ), true );
 f.scrollIntoView();
 }
 catch(e) {
  window.alert( e.message + '.\nSorry about that.' );
 }
 return false;
}

function ask( o, s ) { return o.Popup( s, 0, 'Please confirm', 4 ); }

function esc( s ) {
 return '\'' + s.replace( /\r?\n/g, '\\n' ).replace( /\t/g, '\\t' ).replace( /'/g, '\\\'' ) + '\'';
}

Now what sequence of buttons would lead to the secret message of line 31? Look carefully. No, it isn't a trick question, but perhaps just a bit of danse macabre.

Appendix

One of the possible values for the buttons and one for the icons may be added together as the features parameter of the Popup() method. If either is left out, default zero values apply. According to the Microsoft documentation, these lists are not complete, but the rest has yet to be found. According to experiments on Windows ME and XP, passing a value of 6 or 12 for the buttons makes the popup return 0 before it pops up; 7, 9 and 11 all show a dialog with no buttons (and no reaction to either Return or Esc, the dialog is dismissed by trying to close the main window); 8 gives a regular ‘OK’ and ‘Cancel’ set. When a value of 10 is specified, the dialog features ‘OK’ and ‘Cancel’ buttons, and a mysterious ‘Survey’ button...

Buttons
ValueButtons
0OK
1OK, Cancel
2Abort, Ignore, Retry
3Yes, No, Cancel
4Yes, No
5Retry, Cancel
Icons
ValueDescription
0None
16Critical
32Question
48Exclamation
64Information
Return values
ValueButton
-1None (timed out)
1OK
2Cancel
3Abort
4Retry
5Ignore
6Yes
7No

Reference