oracle.adfmf.framework.api

Class AdfmfSlidingWindowUtilities

Object

oracle.adfmf.framework.api.AdfmfSlidingWindowUtilities

public class AdfmfSlidingWindowUtilities
extends Object

This sliding window utility class provides a programmatic interface to display multiple features on the screen at the same time. Any feature defined within the application that does not appear in the navigation bar and is not the springboard feature may be used with the sliding window plugin API.

There are special threading considerations when calling the show, hide, or destroy APIs in application or feature lifecycle listener methods. Refer to the notes in each of these APIs below.

Method Summary

Methods

Modifier and Type	Method and Description
static String	create(String featureId) Create a sliding window using the specified feature identifier
static boolean	destroy(String windowId) Destroy the sliding window with the specified window identifier.
static String	getCurrentWindowId() Returns the window identifier associated with the current (calling) feature
static String	getTopWindowId() Returns the identifier of the top most (most recently shown) visible overlaid sliding window
static String[]	getWindowIds() Returns an array containing all identifiers for sliding windows that have been created.
static java.util.Map	getWindowInfo(String windowId) Returns information about the specified sliding window as a map
static boolean	hide(String windowId) Hide a sliding window
static boolean	show(String windowId, AdfmfSlidingWindowOptions options) Show a sliding window using the specified display options

Methods inherited from class Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

create

public static String create(String featureId)

Create a sliding window using the specified feature identifier

Creates a sliding window and returns a window identifier that may be used with the other methods of this class. It does not cause the feature to be displayed in any manner nor does it cause the feature's view to be created/activated.

An instance of a feature, identified by its feature id, can be associated with only one sliding window. When calling create with a feature identifier that already has a sliding window the original sliding window identifier will be returned.

The feature supplied can not be a feature that is included in the navigation bar or be the springboard feature.

The return value from create is a string identifying the sliding window for the sole purpose of using in other methods in the plugin. The content returned is undefined for the caller and it should not be used for any other purpose. The content/format of the returned value can change at any time in future plugin iterations.

Example :

 import oracle.adfmf.framework.api.AdfmfSlidingWindowUtilities;
 ...
   try 
   {
     String windowIdentifier = AdfmfSlidingWindowUtilities.create("myFeatureId");
     // Now use the returned window identifer with other methods
     ....
   }
   catch(AdfException e) 
   {
     // handle the exception
   }
 

Parameters:

featureId - the id of the feature to use in the sliding window

Returns:

the window identifier of the sliding window if successful, null otherwise

destroy

public static boolean destroy(String windowId)

Destroy the sliding window with the specified window identifier.

If the window is currently visible a call to hide() will be invoked first. If the feature has been activiated it will be reset. Once destroyed the window identifier is no longer valid and may not be used with any other sliding window methods.

Example :

 import oracle.adfmf.framework.api.AdfmfSlidingWindowUtilities;
 ...
   try 
   {
     String windowIdentifier = AdfmfSlidingWindowUtilities.create("myFeatureId");
     ....   
     boolean bSuccess = AdfmfSlidingWindowUtilities.destroy(windowIdentifier);
   }
   catch(AdfException e) 
   {
     // handle the exception
   }
 

Application or Feature Lifecycle Considerations

In order to prevent a potential temporary deadlock situation that will result in unpredictable behavior any invocations of the show, hide, and destroy methods must be performed in a new thread when called from an application or feature lifecycle listener method. The created thread must be allowed to run independently of the lifecycle listener method; specifically you should not join or otherwise wait for the spawned thread to complete.

Lifecyle Listener Example

  try 
   {
     final String windowIdentifier = AdfmfSlidingWindowUtilities.create("myFeatureId");
     AdfmfSlidingWindowOptions options  = new AdfmfSlidingWindowOptions();
     ....   
     new Thread(new Runnable()  
      {
       try
       {
         boolean bSuccess = AdfmfSlidingWindowUtilities.destroy(windowIdentifier);
       }
       catch (Throwable t)
       {
          // handle the exception
       }
      }).start();  
   }
   catch(AdfException e) 
   {
     // handle the exception
   }
 
 

Parameters:

windowId - the identifier of the sliding window as returned by create()

Returns:

true if the window was successfully destroyed, false otherwise

show

public static boolean show(String windowId,
           AdfmfSlidingWindowOptions options)

Show a sliding window using the specified display options

The show method accepts two parameters. The first parameter, the windowId, is required and is the identifier of the window to display as returned by the create method. The second parameter is also required. It is an AdfmfSlidingWindowOptions object that defines how the sliding window should be displayed. This includes the size, anchor point, animation style and duration, and other relevant details. These options are defined in the AdfmfSlidingWindowOptions class.

The show method can be called any number of times on a sliding window. The AdfmfSlidingWindowOptions supplied on each call will be evaluated to determine if the position or size of the sliding window needs to be updated. For example calling show with a 25% width and then subsequently calling show with 75% width would cause the window to be re-sized. Most AdfmfSlidingWindowOptions can be changed with each call -- that is you could change the size and direction, causing the window to be re-sized and re-positioned in the application. You cannot change the style (pinned or overlaid) between calls to show. The style value used the first time a window is shown must be used throughout the lifetime of that window.

Calling show with the overlaid style will will always bring the specified window to the top, z-order wise, even if the AdfmfSlidingWindowOptions result in no change in layout.

Show does not restart the feature's content. If the feature has been shown, then hidden, and shown again the feature's content will remain unchanged from the first time shown was called.

Show uses the sliding window options passed in to completely replace the previously used options. If you call show passing in a subset of the AdfmfSlidingWindowOptions the corresponding default values will be used and these options will completely replace any previously used options.

Example :

 import oracle.adfmf.framework.api.AdfmfSlidingWindowUtilities;
 import oracle.adfmf.framework.api.AdfmfSlidingWindowOptions;
 ...
   try 
   {
       String windowIdentifier = AdfmfSlidingWindowUtilities.create("myFeatureId");
       AdfmfSlidingWindowOptions myOptions = new AdfmfSlidingWindowOptions();
       myOptions.setSize("25%");
       myOptions.setDirection(AdfmfSlidingWindowOptions.DIRECTION_RIGHT);
       boolean bSuccess = AdfmfSlidingWindowUtilities.show(windowIdentifier, myOptions)
   }
   catch(AdfException e) 
   {
     // handle the exception
   }
 

Application or Feature Lifecycle Considerations

In order to prevent a potential temporary deadlock situation that will result in unpredictable behavior any invocations of the show, hide, and destroy methods must be performed in a new thread when called from an application or feature lifecycle listener method. The created thread must be allowed to run independently of the lifecycle listener method; specifically you should not join or otherwise wait for the spawned thread to complete.

Lifecyle Listener Example

  try 
   {
     final String windowIdentifier = AdfmfSlidingWindowUtilities.create("myFeatureId");
     AdfmfSlidingWindowOptions options  = new AdfmfSlidingWindowOptions();
     ....   
     new Thread(new Runnable()  
      {
       try
       {
         boolean bSuccess = AdfmfSlidingWindowUtilities.show(windowIdentifier,options);
       }
       catch (Throwable t)
       {
          // handle the exception
       }
      }).start();  
   }
   catch(AdfException e) 
   {
     // handle the exception
   }
 
 

Parameters:

windowId - the identifier of the sliding window to show

options - the options defining how the window should be displayed

Returns:

true if the window was successfully shown, false otherwise

See Also:

AdfmfSlidingWindowOptions

hide

public static boolean hide(String windowId)

Hide a sliding window

The hide method uses most recently used AdfmfSlidingWindowOptions used in show call to remove from view the specified sliding window in an animated style. If the window was shown initially using the left direction then shown again using right, thus moving the window, the hide method will use the right direction when animating the window offscreen.

If the windowId is not specified the window assocatiated with the calling feature will be used. Calling hide without supplying a window identifier will itself when called from within a visible sliding window.

Hide does not destroy the window or the feature's web view/state. The window created by create can be shown and hidden multiple times without changing the current feature's state or content.

Example :

 import oracle.adfmf.framework.api.AdfmfSlidingWindowUtilities;
 ...
   try 
   {
       boolean bSuccess = AdfmfSlidingWindowUtilities.hide(windowIdentifier);
   }
   catch(AdfException e) 
   {
     // handle the exception
   }
 

Application or Feature Lifecycle Considerations

In order to prevent a potential temporary deadlock situation that will result in unpredictable behavior any invocations of the show, hide, and destroy methods must be performed in a new thread when called from an application or feature lifecycle listener method. The created thread must be allowed to run independently of the lifecycle listener method; specifically you should not join or otherwise wait for the spawned thread to complete.

Lifecyle Listener Example

  try 
   {
     final String windowIdentifier = AdfmfSlidingWindowUtilities.create("myFeatureId");
     AdfmfSlidingWindowOptions options  = new AdfmfSlidingWindowOptions();
     ....   
     new Thread(new Runnable()  
      {
       try
       {
         boolean bSuccess = AdfmfSlidingWindowUtilities.hide(windowIdentifier);
       }
       catch (Throwable t)
       {
          // handle the exception
       }
      }).start();  
   }
   catch(AdfException e) 
   {
     // handle the exception
   }
 
 

Parameters:

windowId - optional, the identifier of the sliding window

Returns:

true if the window was actually hidden (e.g. was visible)

getWindowInfo

public static java.util.Map getWindowInfo(String windowId)

Returns information about the specified sliding window as a map

The map returned contains the following keys:

Key	Included When Window Is Not Visible	Description
x	N	The x coordinate of the window within the application's main window region. (0,0) refers to the upper leftmost point
y	N	The y coordinate of the window within the application's main window region. (0,0) refers to the upper leftmost point
width	N	The width of the window, in pixels
height	N	The height of the window, in pixels
parentX	N	The x coordinate window/view which can display plugins. This origin will always be zero.
parentY	N	The y coordinate window/view which can display plugins. This origin will always be zero.
parentWidth	Y	The width of the window/view which can display plugins, in pixels
parentHeight	Y	The height of the window/view which can display plugins, in pixels
animationStyle	N	The most recently used animation style used to show the window
duration	N	The most recently used duration used in the show window call, in milliseconds
sizeMode	N	The mode used to interpret the size parameter during the last show window call. Can be 'absolute' or 'percent'
visible	Y	true if the window is currently visible, false otherwise
windowId	Y	the window's identifier
direction	N	the most recently used direction option used in the call to show
style	Y	The style (overlaid or pinned) used to create the sliding window.

Example :

 import oracle.adfmf.framework.api.AdfmfSlidingWindowUtilities;
 ...
   try 
   {
       Map windowInfo = AdfmfSlidingWindowUtilities.getWindowInfo(windowIdentifier);
   }
   catch(AdfException e) 
   {
     // handle the exception
   }
 

Parameters:

windowId - the identifier of the sliding window to obtain information about

Returns:

a map containing the information.

getTopWindowId

public static String getTopWindowId()

Returns the identifier of the top most (most recently shown) visible overlaid sliding window

Example :

 import oracle.adfmf.framework.api.AdfmfSlidingWindowUtilities;
 ...
   try 
   {
       String windowIdentifier = AdfmfSlidingWindowUtilities.getTopWindowId();
   }
   catch(AdfException e) 
   {
     // handle the exception
   }
 

Returns:

the identifier of the sliding window

getWindowIds

public static String[] getWindowIds()

Returns an array containing all identifiers for sliding windows that have been created.

The identifiers for all windows that exist are returned. A window that has been created then destroyed will not be returned in this list. Windows returned are not necessarily visible windows. They may have been created but not shown.

The order of the window identifiers returned is not defined. The caller should make no assumptions about the order returned from this method.

Example :

 import oracle.adfmf.framework.api.AdfmfSlidingWindowUtilities;
 ...
   try 
   {
       String[] windowIdentifiers = AdfmfSlidingWindowUtilities.getWindowIds();
   }
   catch(AdfException e) 
   {
     // handle the exception
   }
 

Returns:

an array of window identifiers, or an empty array if no sliding windows exist

getCurrentWindowId

public static String getCurrentWindowId()

Returns the window identifier associated with the current (calling) feature

Example :

 import oracle.adfmf.framework.api.AdfmfSlidingWindowUtilities;
 ...
   try 
   {
       String windowIdentifier = AdfmfSlidingWindowUtilities.getCurrentWindowId();
   }
   catch(AdfException e) 
   {
     // handle the exception
   }
 

Returns:

the calling feature's sliding window identifier, or null if the feature isn't in a sliding window