★ wanayoo — archive 1999 http://developer.iplanet.com/docs/technote/javascript/window/index.htmlNouvelle recherche | Portail wanayoo
iPlanet

You are here:  Home > Developers > TechNotes > JavaScript > JavaScript TechNote
JavaScript TechNote
 iPlanet Developers
Developer Program
  Membership
  One-to-One Support
  Newsgroups
  Member Services

Developer Publications
  View Source
  Developer News

Documentation
  Technical Manuals
  White Papers
  TechNotes
  Sample Code
  FAQs
  Books

Technologies
  Application Server   CSS
  DOM
  CORBA
  Directory & LDAP
  Dynamic HTML
  Java
  JavaScript
  Linux
  RDF
  Security
  SSJS
  XML
  XUL

Developer Downloads
  Tools & SDKs
  Patches

iPlanet Products
  Technical Resources










spacer
JavaScript 1.2 New Window Methods and Properties

By Mark Lavi
Technology Evangelist, Netscape Communications

INTRODUCTION

JavaScript 1.2 in Netscape Communicator's Navigator 4.0 component has greatly advanced the knowledge and control JavaScript has over the user experience. JavaScript 1.2 can create and dynamically manipulate rich functioned windows, load HTML 3.2 content into them, and capture many user interface events. This gives the JavaScript developer an unprecedented opportunity to control the user experience in the Communicator environment, giving the developer a robust, light-weight way to create crossware applications.

This TechNote assumes the reader is familiar with the JavaScript object hierarchy of documents, windows, and frames in Navigator as well as familiar with signed JavaScript. The body of this document may be browsed and printed with any browser, but this TechNote also contains interactive demonstrations of the new functionality and requires a JavaScript 1.2 capable browser to try them.

OVERVIEW

Netscape has made the new Navigator 4.0 basic user interface and features, toolbars, and navigation button functions accessible by JavaScript 1.2. An overview of what's new and modified for window features:

  • Window Properties
    • Dimensions: innerHeight, innerWidth, outerHeight, outerWidth
    • Toolbar Objects: locationbar, menubar, personalbar, statusbar, toolbar, scrollbars
  • Window Methods
    • Navigation: home, back, forward, find, stop
    • Manipulation: moveBy, moveTo; resizeBy, resizeTo; scrollBy, scrollTo
    • open has these new features:
      • alwaysLowered, alwaysRaised
      • dependent
      • hotkeys
      • innerHeight, innerWidth, outerHeight, outerWidth
      • screenX, screenY
      • titlebar
      • z-lock
  • Backwards compatibility:
    • scroll equates to the new scrollTo, which has extended functionality
    • open(height,width) equates to the new open(innerHeight,innerWidth)
  • Related new functionality in JavaScript 1.2:

THE NEW WINDOW PROPERTIES

DIMENSIONS: INNERHEIGHT, INNERWIDTH, OUTERHEIGHT, OUTERWIDTH

These window properties are expressed in pixel dimensions. These properties are initially set upon window creation with the open method and can be dynamically manipulated by the new window methods.

Window properties that begin with "inner" (innerHeight, innerWidth) represent a pixel dimension of the referenced window's content area. Window properties that begin with "outer" (outerHeight, outerWidth) represent a pixel dimension of the referenced window's outer boundary.The outer boundary includes the scroll bars, the status bar, the tool bars, and other "chrome" (window border user interface elements).

outer window boundary properties:
self.outerWidth == ; self.outerHeight == ;
inner window content boundary properties:
self.innerWidth == ; self.innerHeight == ;
Reload this page for an update:
<BODY onLoad="show_window_properties();">

Here is the function show_window_properties that is called when loading this document:

function show_window_properties() { //Last revision 4/29/97
document.current_win_props.prop_outW.value = self.outerWidth;
document.current_win_props.prop_outH.value = self.outerHeight;
document.current_win_props.prop_inW.value  = self.innerWidth;
document.current_win_props.prop_inH.value  = self.innerHeight;
} // end function show_window_properties
TOOLBAR OBJECTS: LOCATIONBAR, MENUBAR, PERSONALBAR, STATUSBAR, TOOLBAR, SCROLLBARS

The toolbars may now be dynamically displayed (shown or hidden) when controlled by signed JavaScript. The figure shows Navigator 4.0 Toolbars, they are named (from the top to the bottom):Figure 1: Navigator 4.0 Toolbars

  • menubar: the drop-down menus -- File, Edit, View, Go, Communicator, etc.
  • toolbar: the navigation buttons -- Back, Forward, Reload, Home, etc.
  • locationbar: the bookmark and URL areas.
  • personalbar: the user's personal easy access bookmarks.
  • scrollbars: vertical and horizontal document scrollbars.
  • statusbar: security indicator, Navigator status, etc.


All of the toolbars are objects with one property: visible. Visible is binary, it may be set to [true or false], or set to [1 or 0], respectively to represent displayed or hidden toolbar object state. The following example would make the referenced window "chromeless" (chromeless windows lack toolbars, scrollbars, status areas, etc. much like a dialog box) by hiding most of the user interface toolbars: 

self.menubar.visible=false;
self.toolbar.visible=false;
self.locationbar.visible=false;
self.personalbar.visible=false;
self.scrollbars.visible=false;
self.statusbar.visible=false;

THE NEW WINDOW METHODS

This section includes working interactive examples of JavaScript 1.2 new window methods. The first example is a demonstration of navigation frameset (nav_frameset.html) which contains two rows of frames, window methods in the top row navigation frame control the display in the lower row content frame. The second example shows dynamic manipulation of a window (dynamic.html).

NAVIGATION: HOME, BACK, FORWARD, FIND, STOP

These examples illustrate how JavaScript 1.2 can reproduce Navigator 4.0's navigation toolbar button functionality for a window. Please open a new window by selecting the button before trying any of these navigation examples:

Begin each example by selecting this button to open the demonstration window:
  • forward, back, home, stop window functions:
    1. If you haven't already done so, follow this link to the open the demonstration window button.
    2. Follow instructions in the lower frame: select the links three times to load the window's history.
    3. Experiment with selecting the navigation buttons in the upper frame: they manipulate the lower frame's usage history and load the appropriate URLs.
  • find window function:
    1. If you haven't already done so, follow this link to the open the demonstration window button.
    2. If you like, change the search string here:
    3. Then:
      nav_frameset.content.find(this.form.searchstring.value);
    4. The lower content frame of the window will be searched for the above search string. If it is found, it will be highlighted.
  • Another demonstration of stop window function:
    1. If you haven't already done so, follow this link to the open the demonstration window button.
    2. Load a large (71 Kb) image:
    3. Quickly press this button while the image is loading:
      nav_frameset.frames.content.stop();
    4. Observe that the image load is incomplete (unless it has been cached on disk or in memory).
MANIPULATION: MOVEBY, MOVETO; RESIZEBY, RESIZETO; SCROLLBY, SCROLLTO

Previously, the JavaScript developer could only set window properties at window creation, forcing the developer to close an existing window and open a new window with different window properties. Here are working examples of how JavaScript can dynamically manipulate a window after it is created.

The parameters used by these methods are either absolute or relative coordinates in pixel units, given as: (horizontal x-coordinate, vertical y-coordinate). The origin of the axes is at absolute position (0,0), which is the upper left-hand corner of the entire display.

Begin by selecting this button:

All of the window methods ending in "by" (moveBy, resizeBy, scrollBy) use relative pixel arguments, they manipulate the window by adding or subtracting an integer amount of pixels to the current window property. All of the window methods ending in "to" (moveTo, resizeTo, scrollTo) use absolute pixel arguments, they change the window from the current setting to the dimension(s) of the integer amount of pixels specified.

  • moveBy, moveTo:
    • These methods place the named window in a new location on the screen. The new location determines the upper left-hand corner of the window.
    • Exceeding any of the boundaries of the screen (to hide some or all of a window) requires signed JavaScript, so a window won't move past the screen boundaries. (Consider this to be a user interface safety feature which can be overridden when responsibility can be attributed to a source.) Examples: 
      self.moveBy(-5,10); // relative positioning
/* Moves the current window five pixels up towards the top of the screen (x-axis),
   and ten pixels towards the right (y-axis) of the current window position. */
self.moveTo(25,10); // absolute positioning
/* Moves the current window twenty-five pixels from the top boundary of the screen (x-axis),
   and ten pixels from the left boundary of the screen (y-axis). */
    • resizeBy, resizeTo:
      • These methods redimension the named window by setting the outerWidth and outerHeight properties. The upper left-hand corner remains anchored and the lower right-hand corner moves.
      • Absolute or relative resizing of a window which would lead to a final window dimension smaller than 100x100 pixels requires signed JavaScript, so a window won't resize to smaller dimensions than 100x100 pixels. (Consider this to be a user interface safety feature which can be overridden when responsibility can be attributed to a source.) Examples: 
        self.resizeBy(-5,10); // relative positioning
/* Makes the current window five pixels horizontally smaller (x-axis), and
   ten pixels vertically taller (y-axis) from the current window dimensions. */
self.resizeTo(25,20); // absolute positioning
/* Makes the current window dimension twenty-five pixels horizontally wide
   (x-axis), and twenty pixels vertically tall (y-axis). */
      • scrollBy, scrollTo:
        • These methods scroll the content in named window if unviewable portions exist outside of the window (Note: it must be possible to scroll the window, as set by the scrollbars object, otherwise nothing will happen). Examples: 
          self.scrollBy(-5,30); // relative positioning
/* Scrolls the current window five pixels towards the left (x-axis),
   and thirty pixels down towards the bottom of the window (y-axis)
   from the current position in the window (if possible). */
self.scrollTo(0,20); // absolute positioning
/* Scrolls the current window to the left-most boundary (x-axis),
   and twenty pixels down from the top of the window (y-axis) (if possible). */
        • OPEN WINDOW METHOD: NEW FEATURES
        Figure 2: The User's Display and relation to window properties

        The open window method creates a new web browser window. The syntax remains the same for the open method arguments (URL, windowname, windowfeatures) and the windowfeatures argument is still a comma delimited list (i.e.: option=value,option2=value). However, the windowfeatures argument has been expanded to include new options:

        • alwaysRaised, alwaysLowered (binary valued, requires signed JavaScript)
          When set to true, these methods will create a window that floats above or below (respectively) all the other windows. Setting to false gives the window normal behavior, allowing other windows to display over and under it.
        • z-lock (binary valued, requires signed JavaScript)
          When set to true, creates a new window that will not rise above other existing windows (in contrast to alwaysRaised which will rise above all existing and future created windows). This feature may deviate based upon the underlying operating system's window manager, a z-locked window may be below all other Navigator controlled windows or it may be below all windows.
        • dependent (binary valued)
          When set to true, creates a new child window (a new separate window, outside of the current window) and makes the current window it's parent. If the parent window is closed, all the children will close as well.
        • hotkeys (binary valued)
          When set to true, disables most hotkeys with the exception of the security and quit (i.e.: CONTROL-key and ALT-key combinations) in a new window without a menubar.
        • innerHeight, innerWidth, outerHeight, outerWidth (pixel values)
          These options set the new window properties, they are explained in the corresponding section of this TechNote (above). Note: innerHeight and innerWidth options replace the height and width options, but they remain for backwards compatibility.
        • screenX, screenY (pixel values)
          The location of the upper left-hand corner of the new window, in relation to the origin (0,0) of the upper left-hand corner of the user's display.
        • titlebar (binary valued, requires signed JavaScript)
          Creates a window with a displayed or hidden title bar, when set to true or false, respectively.

        Binary values are set to [yes or no] or [1 or 0], respectively. The pixel values are positive integers falling into the current dimensions of the display screen. Pixel values with negative values, with dimensions smaller than 100x100, or with dimensions that exceed the viewable screen (placing a portion or all of the window off screen) require signed JavaScript. Signed JavaScript is required for setting any of window features that fall outside of the user's direct control.

        RELATED NEW FUNCTIONALITY IN JAVASCRIPT 1.2

        Two new features round out JavaScript's new window capabilities: an additional document method yields information on user interaction and a new object which gives you the current display screen properties.

        • document.getSelection()
          This new document method will return the selected (highlighted) area in the current document. Note that the scope of this method is the current document, you are prevented from determining selected areas in another document.window as a safety measure for the user. Here's an example:
          1. Highlight anything in this window now.
          2. Then:
            alert('You have highlighted:\n'+document.getSelection());
        • screen object:
          This object contains properties about the display screen and colors:
          • width: display screen width (number of pixels).
          • height: display screen height (number of pixels).
          • pixelDepth: display screen color resolution (bits per pixel).
          • colorDepth: the bit depth of the color palette, if one is in use, otherwise derived from screen.pixelDepth (bits per pixel).

          Current screen properties:
          Here is the function screen_properties(), it is called when this document is loaded. 
          function screen_properties() {
document.examples.results.value = "("+screen.width+" x "+screen.height+") pixels, "+
	screen.pixelDepth +" bit depth, "+
	screen.colorDepth +" bit color palette depth.";
} // end function screen_properties

        SIGNED JAVASCRIPT REFERENCES

        Creating signed JavaScripts is not covered in this TechNote. It requires processing your JavaScript file(s) with Netscape Object Signing Tools to sign the files and then sourcing the archive with the new ARCHIVE and ID attributes of the <SCRIPT> HTML tag. Signed JavaScript has extended capabilities for cases where user security or user control may be compromised.

        Please refer to these resources:

spacer spacer


                                                       
iPlanet International | Year 2000 | Site Map | Feedback
Products | Solutions | Support | Services | Download | About Us | Developer
© 2000 Sun-Netscape Alliance. All Rights Reserved  Privacy Policy