com.livescribe.penlet
Class Region

java.lang.Object
  com.livescribe.penlet.Region

public final class Region
extends Object

This class encapsulates a region of interest for an application. A region is identified uniquely by a 64-bit number composed of the following attributes.

Property	Description
Area ID	An identifier used by application to identify a region. One or more regions within the app can have the same area ID.
Instance ID	The instance identifer of the application. The application actually does not not have any control over this value. When creating dynamic regions, the value is set once that region has has been registered using RegionCollection.addRegion(Shape, Region).
Occlusive	Indicates if the region masks any other regions having a higher Z-order that occupy the same physical space on the page.
Subtractive	Not relevant to developers at this time.
Z-order	Indicates the order of ovrelapping regions. A lower value indicates that the region is "closer" to the person drawing on the page. In other words, the pen will "hit" lower-numbered regions first. This is another value that may be modified by adding a region to the application's region collection. A Z-order of zero tells the system to assign one.
Store Strokes	Indicates that the region should cause any strokes drawn within it to be stored. Please see the method docs for more information.
Bitmap	Indicates if the region consists of a shape divided into multiple uniform cells. This is not relevant to developers at this time.

The following table summarizes the structure of the 64-bit value.

Bit Count	Property
1 bit	Reserved
15 bits	Z-order
8 bits	Reserved
16 bits	Instance ID
16 bits	Area ID
1 bit	Store Strokes
1 bit	Bitmap
1 bit	Tablet
3 bits	Reserved
1 bit	Occlusive
1 bit	Subtractive

Note that lower region ID's have a higher precedence than higher ID's. For example, if two regions have the same Z-order but have different area ID's, then the one with the lower area ID is considered to be "on top of" the one with the higher area ID.

Constructor Summary

Region(int area)
Creates a new region having the specified area ID.

Region(int area, boolean occlusive)
Creates a new region having the specified area ID and occlusive state.

Region(int area, boolean occlusive, boolean storeStrokes)
Creates a new region having the specified area ID, and occlusive and store strokes states.

Region(int area, int zOrder, boolean occlusive, boolean subtractive)
Creates a new region having the specified area ID, Z-order, and occlusive and subtractive states.

Region(int area, int zOrder, boolean occlusive, boolean subtractive, boolean storeStrokes)
Creates a new region having the specified values.

Region(int area, int zOrder, boolean occlusive, boolean subtractive, boolean storeStrokes, boolean tablet)
Creates a new region having the specified values.

Region(long id)
Creates a new Region with the specified 64-bit ID.

Method Summary

boolean	equals(Object obj) Checks whether the given object is equal to this region.
boolean	equals(Region that) Deprecated. Use equals(Object).
int	getAreaId() Gets the area ID, a 16-bit unsigned value.
long	getId() Gets the unique 64-bit region ID.
String	getIdString() Returns the ID as a string in hex, having the following format: 0xHIGH_WORD:LOW_WORD.
int	getInstance() Gets the penlet instance that owns this region.
int	getZOrder() Gets the Z-order of the shape.
int	hashCode() Returns a hash code for this region.
boolean	isBitmapRegion() Indicates if the region is a bitmap Region.
boolean	isOcclusive() Indicates if this region physically blocks or hides another region on the page.
boolean	isStrokesStored() Indicates if the region stores strokes or not.
boolean	isSubtractive() Indicates if the shape is subtractive.
boolean	isTabletRegion() Indicates if the region is a tablet Region.
String	toString() Returns a string representation of this object.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Region

public Region(long id)

Creates a new Region with the specified 64-bit ID. Please see the class documentation for details about the bit format.

Parameters:

id - the 64-bit region ID

See Also:

Region

Region

public Region(int area,
              boolean occlusive)

Creates a new region having the specified area ID and occlusive state. The following table specifies the defaults for the other propreties.

Property	Default Value
Store Strokes	false
Subtractive	false
Z-order	Zero (system assigned later)
Bitmap	false
Tablet	false

Parameters:

area - the area ID

occlusive - true if occlusive and false otherwise

Region

public Region(int area,
              boolean occlusive,
              boolean storeStrokes)

Creates a new region having the specified area ID, and occlusive and store strokes states. The following table specifies the defaults for the other propreties.

Property	Default Value
Subtractive	false
Z-order	Zero (system assigned later)
Bitmap	false

Parameters:

area - the area ID

occlusive - true if occlusive and false otherwise

storeStrokes - true to store strokes and false otherwise

Region

public Region(int area,
              int zOrder,
              boolean occlusive,
              boolean subtractive)

Creates a new region having the specified area ID, Z-order, and occlusive and subtractive states. The following table specifies the defaults for the other propreties.

Property	Default Value
Store Strokes	false
Bitmap	false

Parameters:

area - the area ID

zOrder - the Z-order

occlusive - true if occlusive and false otherwise

subtractive - true if subtractive and false otherwise

Region

public Region(int area)

Creates a new region having the specified area ID. The following table specifies the defaults for the other propreties.

Property	Default Value
Store Strokes	false
Occlusive	false
Subtractive	false
Z-order	Zero (system assigned later)
Bitmap	false
Tablet	false

Parameters:

area - the area ID

Region

public Region(int area,
              int zOrder,
              boolean occlusive,
              boolean subtractive,
              boolean storeStrokes)

Creates a new region having the specified values. The following table specifies the defaults for the other propreties.

Property	Default Value
Bitmap	false
Tablet	false

Parameters:

area - the area ID

zOrder - the Z-order

occlusive - true if occlusive and false otherwise

subtractive - true if subtractive and false otherwise

storeStrokes - true to store strokes and false otherwise

Region

public Region(int area,
              int zOrder,
              boolean occlusive,
              boolean subtractive,
              boolean storeStrokes,
              boolean tablet)

Creates a new region having the specified values. The following table specifies the defaults for the other propreties.

Property	Default Value
Bitmap	false

Parameters:

area - the area ID

zOrder - the Z-order

occlusive - true if occlusive and false otherwise

subtractive - true if subtractive and false otherwise

storeStrokes - true to store strokes and false otherwise

tablet - true to work as a paper tablet false otherwise

Since:

2.5

Method Detail

getId

public long getId()

Gets the unique 64-bit region ID. This value contains all the region properties.

Returns:

the long Region ID.

getAreaId

public int getAreaId()

Gets the area ID, a 16-bit unsigned value. This is used by the application to identify this region. It is possible for more than one region to have the same area ID.

Returns:

the area ID, an unsigned 16-bit value.

getInstance

public int getInstance()

Gets the penlet instance that owns this region. This is an unsigned 16-bit value.

Returns:

the instance ID, an unsigned 16-bit value.

getZOrder

public int getZOrder()

Gets the Z-order of the shape. A higher Z-order means that the region is "farther back". In other words, a lower Z-order is considered to be "on top" of regions with a higher Z-order. This is an unsigned 15-bit value.

A region created having a Z-order of zero causes the system to choose one for you when it is added to the penlet's region collection.

Returns:

the Z-order, an unsigned 15-bit value.

isOcclusive

public boolean isOcclusive()

Indicates if this region physically blocks or hides another region on the page. In other words, a non-occlusive region will cause regions "below" this one (a higher Z-order) to also trigger events (in addition to this one) when the pen tip enters this spot on the page.

Returns:

whether the shape covers other shapes that have a higher Z-order.false the shape is transparent and shapes behind can trigger events.

isSubtractive

public boolean isSubtractive()

Indicates if the shape is subtractive. Note that this bit is only relevant to Composite shapes

Returns:

true the shape cuts a hole in the shape false the shape is a normal additive shape.

isBitmapRegion

public boolean isBitmapRegion()

Indicates if the region is a bitmap Region. A bitmap region consists of a shape that is divided into multiple uniform cells, typically rectangular.

Returns:

true the shape is a bitmap Region false the shape is not a bitmap Region.

isStrokesStored

public boolean isStrokesStored()

Indicates if the region stores strokes or not. The rule is that if any intersected shape does not want to store strokes, the strokes are not stored. This uses the occlusive bits, so if strokes must be stored, place the storing region with lower Z-order and set the region's occlusive bit. Note that this bit is only relevant to "composite" shapes.

Returns:

true if the shape stores strokes and false otherwise.

isTabletRegion

public boolean isTabletRegion()

Indicates if the region is a tablet Region. A tablet region can make the pen act like a mouse and send other custom commands to the PC.

Returns:

true if the shape is a tablet region and false otherwise.

Since:

2.5

equals

public boolean equals(Region that)

Deprecated. Use equals(Object).

Determines if this region is equal to the specified region. This compares the 64-bit ID's.

Parameters:

that - compare to this region

Returns:

whether the reference to the given region is equal to <.

equals

public boolean equals(Object obj)

Checks whether the given object is equal to this region. This compares the 64-bit ID's.

Overrides:

equals in class Object

Parameters:

obj - compare to this object

Returns:

whether the specified object is considered equal to this region.

See Also:

Boolean.hashCode(), Hashtable

hashCode

public int hashCode()

Returns a hash code for this region. This is calculated in the same manner as Long.hashCode() using this region's 64-bit ID.

Overrides:

hashCode in class Object

Returns:

a hash code for this object.

See Also:

Object.equals(java.lang.Object), Hashtable

toString

public String toString()

Returns a string representation of this object.

Overrides:

toString in class Object

Returns:

a string representation of this object.

getIdString

public final String getIdString()

Returns the ID as a string in hex, having the following format: 0xHIGH_WORD:LOW_WORD.

Returns:

the ID string in hex.