Copyright: Actuate Software Corporation


  Actuate Foundation Class Reference

The Actuate Foundation Class Reference provides information for using the Actuate foundation classes, their variables, properties, and methods.

The Actuate Foundation Class Reference includes the following sections.

Summary of classes and methods. This section provides  a summary of classes and methods. For a diagram of the inheritance hierarchy, see the Actuate Foundation Class Reference in printed form or online PDF format.

AFC classes. This section contains an alphabetical listing of the classes. Each class description includes a variables, properties, and methods summary followed by an alphabetical listing of the methods.

AFC data types. This section lists the AFC data types.


Summary of classes and methods

The Actuate Foundation Class library contains classes and methods that support building a wide range of custom reports. Some classes are appropriate for you to use for this purpose and others are not. For example, it is important to understand that abstract base classes define the core protocol--the rules governing the use of these classes. These classes are never instantiated and contain general rules that other classes refine. Before you begin using the class library, you should be familiar with the concepts in Part II: Programming with the Actuate Foundation Classes in Programming with Actuate.

The tables in this section change from time to time as we modify the product architecture to meet customer needs. We reserve certain classes as private in the same way as we reserve certain words in the Actuate Basic language. Private classes must never be modified.

In the following tables, we describe the methods as callable, overridable, or private. In addition, we call out abstract base classes. The tables are grouped. The groupings are:

•	Report section classes and methods

•	Page layout classes and methods

•	Control classes and methods

•	Connection classes and methods

•	Collection classes and methods

•	Data stream classes and methods

•	Internal tools classes and methods


Report section classes and methods

Use report section classes and methods to modify your report structure.

Class or method	Classification
AcComponent
ApplyVisitor( )	Callable
Delete( )	Overridable
GetContentName( )	Callable
IsPersistent( )	Callable
New( )	Overridable
NewComponent( )	Callable
NewPersistentComponent( )	Callable
SetProperties( )	Private
AcReportComponent
Abandon( )	Callable
AddContent( )	Callable
AddToPageList( )	Callable
ApplyVisitor( )	Callable
Build( )	Overridable
BuildIntoFlow( )	Private
BuildFromRow( )	Overridable
BuildFromRowIntoFlow( )	Private
BuildTocList( )	Overridable
DetachFromContainer( )	Callable
DetachContent( )	Callable
Finish( )	Overridable
GenerateHtml( )	Overridable
GenerateHtmlStructure( )	Private
GetAggregateValue( )	Private
GetContainer( )	Callable
GetContents( )	Callable
GetContentCount( )	Callable
GetContentIterator( )	Callable
GetFirstTocChild( )	Private
GetFirstContent( )	Callable
GetPage( )	Callable
GetPageIndex( )	Callable
GetPageList( )	Callable
GetRowCount( )	Callable
GetReport( )	Callable
GetConnection( )	Callable
GetDataStream( )	Callable
GetFirstContentFrame( )	Callable
GetTocList( )	Overridable
GetFirstTocChild( )	Private
GetNextTocChild( )	Private
GetPage( )	Callable
GetTocEntry( )	Overridable
GetVisualComponent( )	Private
HasContents( )	Callable
HasTocChildren( )	Private
IsBlocked( )	Private
IsContainer( )	Callable
IsFrame( )	Callable
IsLeaf( )	Callable
IsVisual( )	Callable
OnRow( )	Overridable
PrebuildFromRow( )	Private
SetTocEntry( )	Overridable
Start( )	Overridable
Terminate( )	Private
AcReport
ApplyVisitor( )	Callable
Build( )	Private
BuildReport( )	Private
GetContent( )	Callable
GetContents( )	Callable
GetDefaultDataControlFont( )	Callable
GetDefaultLabelControlFont( )	Callable
GetHtmlDir( )	Overridable
GetPageList( )	Callable
GetReport( )	Callable
GetRowFileName( )	Overridable
GetTwipsPerPixel( )	Overridable
IsTransientReport( )	Private
NewContent( )	Callable
NewPageList( )	Callable
NewViewer( )	Callable
OnFinishViewer( )	Overridable
OnStartViewer( )	Overridable
RoiIsTemporary( )	Overridable
SuggestRoiName( )	Overridable
TocAddComponent( )	Callable
AcHtmlReport
ApplyVisitor( )	Callable
Build( )	Private
CustomHtmlBody( )	Overridable
CustomHtmlHead( )	Overridable
GetServerPrefix( )	Overridable
WantHtml( )	Overridable
SetProperties( )	Private
AcSection
AddContent( )	Callable
ApplyVisitor( )	Callable
BuildFromRow( )	Private
BuildFromRowIntoFlow( )	Private
CommittedToFlow( )	Private
CommitRowToFlow( )	Private
DisableSubpage( )	Private
EnableSubpage( )	Private
Finish( )	Overridable
FinishConnection( )	Overrideable
FinishFlow( )	Overridable
FinishPage( )	Overridable
GetConnection( )	Callable
GetContents( )	Callable
GetCurrentRow( )	Callable
GetPageList( )	Callable
IsBlocked( )	Private
NewConnection( )	Private
NewPage( )	Overridable
NewSubpage( )	Private
ObtainConnection( )	Overridable
Start( )	Overridable
StartFlow( )	Private
StartPage( )	Overridable
StartSubpage( )	Private
StopAfterCurrentRow( )	Callable
StopAfterCurrentFrame( )	Callable
StopNow( )	Callable
Terminate( )	Private
TocAddComponent( )	Callable
TocAddContents( )	Callable
AcDataSection
ApplyVisitor( )	Callable
BeginRow( )	Private
BuildRowContent( )	Private
BuildRowContentIntoFlow( )	Private
CommittedToFlow( )	Callable
FinishContent( )	Private
FinishFlow( )	Overridable
FinishGroup( )	Private
FinishGroupIntoFlow( )	Private
GetAfter( )	Callable
GetBefore( )	Callable
GetPageFooter( )	Callable
GetPageHeader( )	Callable
NewAfter( )	Overridable
NewBefore( )	Overridable
NewContent( )	Overridable
NewPageFooter( )	Overridable
NewPageHeader( )	Overridable
OnEmptyGroup( )	Overridable
SetProperties( )	Private
Start( )	Overridable
StartFlow( )	Overridable
StartGroup( )	Private
StartGroupIntoFlow( )	Private
Terminate( )	Private
AcReportSection
ApplyVisitor( )	Callable
Build( )	Overridable
BuildIntoFlow( )	Private
BuildOnePass( )	Private
BuildTwoPass( )	Private
Finish( )	Overridable
FinishBuild( )	Private
FinishDataStream( )	Overridable
GetAggregateValue( )	Private
GetDataStream( )	Callable
NewDataStream( )	Overridable
ObtainDataStream( )	Overridable
SetSortKey( )	Overridable
SetTocEntry( )	Overridable
Start( )	Overridable
StartBuild( )	Private
StartDataStream( )	Overridable
AcGroupSection
ApplyVisitor( )	Callable
BuildFromRow( )	Overridable
BuildFromRowIntoFlow( )	Private
GetAggregateValue( )	Private
GetKey( )	Private
GetKeyString( )	Callable
SetTocEntry( )	Overridable
Start( )	Overridable
AcConditionalSection
ApplyVisitor( )	Callable
Build( )	Private
BuildFromRow( )	Private
ConditionIsTrue( )	Overridable
NewElse( )	Private
NewThen( )	Private
AcParallelSection
AddReport( )	Callable
ApplyVisitor( )	Callable
Build( )	Overridable
NewContents( )	Private
Start( )	Overridable
StopAfterCurrentFrame( )	Callable
StopNow( )	Callable
AcSequentialSection
ApplyVisitor( )	Callable
Build( )	Overridable
BuildOneRow( )	Private
BuildFromRow( )	Private
NewContent( )	Private
SelectContent( )	Overridable
Start( )	Overridable
StopAfterCurrentFrame( )	Callable
StopAftereCurrentSection( )	Callable
StopNow( )	Callable


Page layout classes and methods

Use page layout classes and methods to customize building frames, flows, and pages.

Class or method	Classification
AcPageList
ActivateFlow( )	Private
ActivateNextFlow( )	Private
ActivateSection( )	Private
ActivateSections( )	Private
AddComponent( )	Private
AddComponentToFlow( )	Private
AddFrame( )	Callable
AddFrameToFlow( )	Private
AddSubpage( )	Private
ApplyVisitor( )	Callable
CommitSection( )	Private
CommitSections( )	Private
CreatePage( )	Private
DeactivateFlow( )	Private
DeactivateFlowTo( )	Private
DeactivatePage( )	Private
DeactivateSection( )	Private
EjectPage( )	Callable
FindFlowWithSpace( )	Private
Finish( )	Overridable
GetActivePage( )	Private
GetContents( )	Callable
GetContentIterator( )	Callable
GetCurrentFlow( )	Callable
GetCurrentPage( )	Callable
GetActivePage( )	Private
GetFirstPage( )	Callable
GetNextPage( )	Private
GetLastPage( )	Callable
GetPage( )	Callable
GetPageCount( )	Callable
GetPageDepth( )	Private
GetPageFooter( )	Private
GetPageHeader( )	Private
GetPreviousPage( )	Private
NewPage( )	Overridable
PopPage( )	Private
PopSection( )	Private
PopSubpage( )	Private
PrepareForOutput( )	Private
PushPageFooter( )	Private
PushPageHeader( )	Private
PushSection( )	Private
PushSubpage( )	Private
Restore( )	Private
ShiftFooterUp( )	Private
Start( )	Overridable
SuspendBelow( )	Private
AcSimplePageList
ApplyVisitor( )	Callable
NewPage( )	Private
AcLeftRightPageList
ApplyVisitor( )	Callable
NewLeftPage( )	Private
NewPage( )	Private
NewRightPage( )	Private
SetProperties( )	Private
Start( )	Overridable
AcTitleBodyPageList
ApplyVisitor( )	Callable
NewBodyPage( )	Private
NewPage( )	Private
NewTitlePage( )	Private
Start( )	Overridable
AcBaseFrame
Abandon( )	Private
AddContent( )	Callable
AddToPageList( )	Private
AdjustDependencies( )	Private
AdjustSize( )	Overridable
ApplyVisitor( )	Callable
Build( )	Overridable
BindToFlow( )	Overridable
ControlDependency( )	Private
FindContentByClass( )	Callable
FindContentByClassID( )	Callable
Finish( )	Overridable
GetContents( )	Callable
GetControlValue( )	Callable
GetPageIndex( )	Private
GetPageNumber( )	Callable
InitializeContentVariables( )	Private
IsFrame( )	Private
MakeContents( )	Private
New( )	Overridable
RebindToFlow( )	Overridable
SetPageIndex( )	Private
SetProperties( )	Private
SplitContents( )	Callable
SplitFrame( )	Overridable
Start( )	Overridable
AcBasePage
AddContent( )	Callable
ApplyVisitor( )	Callable
BalanceFlowContent( )	Private
Finish( )	Overridable
GetNextFlow( )	Private
NewPageState( )	Private
Start( )	Overridable
AcSubPage
ApplyVisitor( )	Callable
BindToFlow( )	Private
ComputeGeometry( )	Private
Finish( )	Overridable
NewPageState( )	Private
RebindToFlow( )	Private
ResizeBy( )	Callable
SetProperties( )	Private
ShrinkToFit( )	Private
Start( )	Overridable
AcPage
ApplyVisitor( )	Callable
FormatPageNumber( )	Overridable
GetPage( )	Callable
GetPageIndex( )	Callable
GetPageNumber	Callable
SetPageIndex	Private
SetProperties( )	Private
AcDataFrame
AddToFlow( )	Private
AddToPageList( )	Private
ApplyVisitor( )	Callable
BindToFlow( )	Overridable
BuildFromRow( )	Private
BuildFromRowIntoFlow( )	Private
BuildIntoFlow( )	Private
GetBorderOrigin( )	Callable
GetBorderRect( )	Callable
GetBorderSize( )	Callable
GetPage( )	Callable
ReBindToFlow( )	Overridable
SetProperties( )	Private
AcFrame
AddToFlow( )	Private
AddToPageList( )	Private
ApplyVisitor( )	Overridable
BindToFlow( )	Overridable
GetBorderOrigin( )	Callable
GetBorderRect( )	Callable
GetBorderSize( )	Callable
GetPage( )	Callable
ReBindToFlow( )	Overridable
SetProperties( )	Private
AcHtmlFrame
ApplyVisitor( )	Callable
SetProperties( )	Private
AcFlow
AddContent( )	Private
AddFooter( )	Overridable
AddFrame( )	Overridable
AddHeader( )	Overridable
AddSubpage( )	Overridable
ApplyVisitor( )	Callable
BindFrame( )	Private
CanFitFrame( )	Callable
GetContents( )	Callable
GetFreeSpace( )	Overridable
GetPage( )	Callable
PlaceFrame( )	Private
ReaddFrame( )	Private
ReleaseSpace( )	Overridable
ReserveSpace( )	Overridable
ResetSpace( )	Overridable
SetProperties( )	Private
ShiftFooterUp( )	Overridable
Start( )	Overridable
AcLinearFlow
AddFrame( )	Overridable
AddHeader( )	Callable
AddSubpage( )	Callable
ApplyVisitor( )	Callable
Finish( )	Overridable
GetFreeSpace( )	Callable
GetInsideOrigin( )	Callable
GetInsideRect	Callable
GetInsideSize( )	Callable
NewFactoryState( )	Private
ResetSpace( )	Callable
AcTopDownFlow
AddFooter( )	Private
AlignFrame( )	Private
CanFitFrame( )	Callable
DetachContent( )	Private
Finish( )	Overridable
PlaceFrame( )	Private
ReleaseSpace( )	Callable
ReserveSpace( )	Callable
ResizeBy( )	Callable
ShiftFooterUp( )	Callable


Control classes and methods

Use control classes and methods to manipulate the position and value of visual controls.

Class or method	Classification
AcVisualComponent
AddMenuCommands( )	Overridable
ApplyVisitor( )	Callable
AttachToPage( )	Private
ButtonSelect( )	Private
GetBottom( )	Callable
GetFrame( )	Callable
GetHeight( )	Callable
GetHtmlLinkTo( )	Private
GetLeft( )	Callable
GetLinkTo( )	Callable
GetPage( )	Callable
GetPixelSize( )	Callable
GetRect( )	Callable
GetRight( )	Callable
GetTop( )	Callable
GetWidth( )	Callable
GetVisualComponent( )	Callable
IsHtmlFlowBreak( )	Private
IsVisual( )	Private
MoveBy( )	Callable
MoveTo( )	Callable
OnActuate( )	Overridable
OnContextMenu( )	Overridable
OnFollowLink( )	Overridable
OnHelp( )	Overridable
OnLButtonClick( )	Overridable
OnLButtonDblClick( )	Overridable
OnLButtonDown( )	Overridable
OnLButtonUp( )	Overridable
ResizeBy( )	Callable
ResizeTo( )	Callable
OnRButtonClick( )	Overridable
OnRButtonDblClick( )	Overridable
OnRButtonDown( )	Overridable
OnRButtonUp( )	Overridable
ShowInHtml( )	Overridable
ShowWhenPrinting( )	Overridable
ShowWhenViewing( )	Overridable
AcControl
ApplyVisitor( )	Callable
Build( )	Private
BuildFromRow( )	Private
GetControlValue( )	Callable
GetHtmlText( )	Overridable
GetText( )	Overridable
GetValue( )	Callable
PageNo( )	Callable
PageNo$( )	Callable
SetDataValue( )	Callable
SetValue( )	Overridable
AcDataControl
ApplyVisitor( )	Callable
Build( )	Private
BuildFromRow( )	Private
Finish( )	Private
FinishAggregate( )	Private
IsSummary( )	Overridable
Searchable( )	Private
Selectable( )	Private
SetProperties( )	Private
SetTocEntry( )	Overridable
SetValue( )	Overridable
AcCurrencyControl
ApplyVisitor( )	Callable
Format( )	Callable
GetText( )	Overridable
GetValue( )	Callable
New( )	Overridable
SearchAttributeName( )	Private
SetDataValue( )	Callable
SetProperties( )	Private
AcDateTimeControl
ApplyVisitor( )	Callable
GetText( )	Overridable
GetValue( )	Callable
New( )	Overridable
SearchAttributeName( )	Private
SetDataValue( )	Callable
SetProperties( )	Private
AcDoubleControl
ApplyVisitor( )	Callable
GetText( )	Overridable
GetValue( )	Callable
New( )	Overridable
SearchAttributeName( )	Private
SetDataValue( )	Callable
SetProperties( )	Private
AcIntegerControl
ApplyVisitor( )	Callable
GetText( )	Overridable
GetValue( )	Callable
New( )	Overridable
SearchAttributeName( )	Private
SetDataValue( )	Callable
SetProperties( )	Private
AcTextControl
ApplyVisitor( )	Callable
GetText( )	Overridable
GetValue( )	Callable
New( )	Overridable
SearchAttributeName( )	Private
SetDataValue( )	Callable
AcEllipseControl
ApplyVisitor( )	Callable
SetProperties( )	Private
AcGraph
ApplyVisitor( )	Callable
ComputeLabels( )	Callable
ComputeMinMax( )	Callable
ComputeXMinMax( )	Private
ComputeYMinMax( )	Private
ComputeZMinMax( )	Private
CustomXLabels( )	Private
CustomYLabels( )	Private
CustomZLabels( )	Private
Finish( )	Overridable
FormatXLabel( )	Overridable
FormatYLabel( )	Overridable
FormatZLabel( )	Overridable
GetHitPoint( )	Callable
GetHitXValue( )	Callable
GetHitYValue( )	Callable
GetHitSet( )	Callable
RenderToFile( )	Overridable
SetProperties( )	Private
AcDetailGraph
AddPoint( )	Callable
ApplyVisitor( )	Callable
BuildFromRow( )	Overridable
GetLabelValue( )	Overridable
GetXValue( )	Overridable
GetYValue( )	Overridable
GetZValue( )	Private
New( )	Overridable
AcHLCGraph
AddPoint( )	Callable
ApplyVisitor( )	Overridable
BuildFromRow( )	Overridable
GetCloseValue( )	Overridable
GetHighValue( )	Overridable
GetLabelValue( )	Overridable
GetLowValue( )	Overridable
GetOpenValue( )	Overridable
SetProperties( )	Private
AcSummaryGraph
No Methods defined
AcImageControl
ApplyVisitor( )	Callable
GetBaseImageName( )	Callable
SetDataValue( )	Callable
SetProperties( )	Private
AcHtmlImageControl
ApplyVisitor( )	Callable
SetProperties( )	Private
AcHtmlObjectControl
No Methods defined
AcHtmlAppletControl
ApplyVisitor( )	Callable
HtmlParams( )	Callable
IsHtmlFlowBreak( )	Private
SetParam( )	Callable
SetProperties( )	Private
AcHtmlPlugInControl
ApplyVisitor( )	Callable
HtmlParams( )	Overridable
IsHtmlFlowBreak( )	Private
SetParam( )	Callable
SetProperties( )	Private
AcLabelControl
ApplyVisitor( )	Callable
GetText( )	Overridable
GetValue( )	Callable
SetDataValue( )	Callable
SetProperties( )	Private
AcLineControl
ApplyVisitor( )	Callable
GetBottom( )	Callable
GetHeight( )	Callable
GetHtmlRuleHeight( )	Callable
GetLeft( )	Callable
GetRight( )	Callable
GetWidth( )	Callable
GetTop( )	Callable
IsHtmlFlowBreak( )	Private
MoveBy( )	Callable
ResizeBy( )	Callable
SetProperties( )	Private
ShowInHtml( )	Overridable
AcHtmlRuleControl
ApplyVisitor( )	Callable
GetHtmlRuleWidth( )	Callable
SetProperties( )	Private
AcOleControl
ApplyVisitor( )	Callable
SetProperties( )	Private
AcOleContainerControl
ApplyVisitor( )	Callable
CloseOrDeactivate( )	Overridable
CreateCloneFrom( )	Private
DoCloseOrDeactivate( )	Private
DoCreateCloneFrom( )	Private
DoFindOleClientItem( )	Private
DoGetKeyValues( )	Private
DoGetObject( )	Private
DoOleVerb( )	Private
DoVerb( )	Overridable
GetContainerItem( )	Private
GetKeyValues( )	Private
New( )	Overridable
OnActivate( )	Overridable
OnCreate( )	Overridable
OnLButtonDblClk( )	Overridable
Object( )	Overridable
Selectable( )	Callable
AcRectangleControl
ApplyVisitor( )	Callable
SetProperties( )	Private
AcObjectArray
AddToTail( )	Callable
GetAt( )	Callable
GetCount( )	Callable
GetHead( )	Callable
GetTail( )	Callable
IsEmpty( )	Callable
New( )	Callable
NewIterator( )	Callable
Remove( )	Callable
RemoveAll( )	Callable
RemoveAt( )	Private
RemoveEmptyEntries( )	Private
RemoveTail( )	Callable
ResizeTo( )	Callable
SetAt( )	Callable
AcArrayIterator
GetNext( )	Callable
HasMore( )	Callable
IsDone( )	Callable
New( )	Callable
Restart( )	Callable
SkipForwardTo( )	Callable


Connection classes and methods

Use connection classes and methods to connect to a data source.

Class or method	Classification
AcConnection
Connect( )	Overridable
Delete( )	Overridable
Disconnect( )	Callable
IsConnected( )	Callable
New( )	Overridable
RaiseError( )	Callable
AcDBConnection
Connect( )	Overridable
Delete( )	Overridable
DeleteConnetion( )	Private
Disconnect( )	Overridable
DoConnect( )	Private
DoDisconnect( )	Private
GetConnectionPtr( )	Private
GetGeneralError( )	Callable
GetGeneralErrorText( )	Callable
GetSpecificError( )	Callable
GetSpecificErrorText( )	Callable
InterfaceName( )	Private
NewConnection( )	Private
Prepare( )	Callable
PutConnectionProperty( )	Private
RaiseError( )	Callable
RetrieveGeneralError( )	Private
RetrieveGeneralErrorText( )	Private
RetrieveSpecificError( )	Private
RetrieveSpecificErrorText( )	Private
SetConnectionProperty( )	Private
AcDB2Connection
Connect( )	Overridable
InterfaceName( )	Private
New( )	Overridable
SetProperties( )	Private
AcInformixConnection
Connect( )	Overridable
InterfaceName( )	Private
New( )	Overridable
SetProperties( )	Private
AcMSSQLConnection
Connect( )	Overridable
InterfaceName( )	Private
New( )	Overridable
SetProperties( )	Private
AcODBCConnection
Connect( )	Overridable
InterfaceName( )	Private
New( )	Overridable
SetProperties( )	Private
AcOracleConnection
Connect( )	Overridable
InterfaceName( )	Private
New( )	Overridable
SetProperties( )	Private
AcProgressConnection
Connect( )	Overridable
InterfaceName( )	Private
New( )	Overridable
SetProperties( )	Private
AcSybaseConnection
Connect( )	Overridable
InterfaceName( )	Private
New( )	Overridable
SetProperties( )	Private
AcSybaseDBLibConnection
Connect( )	Overridable
InterfaceName( )	Private
New( )	Overridable
SetProperties( )	Private
AcDBStatement
AllocateCursor( )	Callable
BindParameter( )	Callable
BindStatementParameter( )	Private
DefineProcedureInputParameter( )	Callable
DefineProcedureOutputParameter( )	Callable
Delete( )	Callable
DeleteStatement( )	Private
DoDefineProcedureParameter( )	Private
DoExecute( )	Private
DoGetOutputParameter( )	Private
DoGetProcedureStatus( )	Private
DoPrepare( )	Private
Execute( )	Callable
GetOutputCount( )	Callable
GetOutputParameter( )	Callable
GetParameterCount( )	Callable
GetProcedureStatus( )	Callable
GetStatementText( )	Callable
New( )	Callable
OpenCursor( )	Callable
Prepare( )	Callable
RetrieveStatementOutputCount( )	Private
RetrieveStatementParameterCount( )	Private
RetrieveStatementText( )	Private
AcDBCursor
BindColumn( )	Callable
BindParameter( )	Callable
Delete( )	Callable
DoAllocateCursor( )	Private
DoBindCursorParameter( )	Private
DoBindOutput( )	Private
DoCloseCursor( )	Private
DoDeleteCursor( )	Private
DoFetch( )	Private
DoOpenCursor( )	Private
DoStartNextSet( )	Private
Fetch( )	Callable
GetConnection( )	Callable
GetStatement( )	Callable
IsOpen( )	Callable
New( )	Callable
OpenCursor( )	Callable
StartNextSet( )	Callable


Collection classes and methods

Use collection classes and methods to work with arrays.

Method	Classification
AcCollection
IsEmpty( )	Callable
GetCount( )	Callable
NewIterator( )	Overridable
RemoveAll( )	Callable
Remove( )	Callable
AcOrderedCollection
AddToTail( )	Callable
GetAt( )	Callable
GetHead( )	Callable
GetTail( )	Callable
RemoveTail( )	Callable
AcList
AddToHead( )	Callable
Contains( )	Callable
Copy( )	Callable
GetIndex( )	Callable
InsertAfter( )	Callable
InsertBefore( )	Callable
RemoveHead( )	Callable
AcSingleList
AddToHead( )	Private
AddToTail( )	Private
Compare( )	Private
Copy( )	Private
FindByValue( )	Private
GetAt( )	Private
GetCount( )	Private
GetHead( )	Private
GetIndex( )	Private
GetTail( )	Private
InsertAfter( )	Private
InsertBefore( )	Private
IsEmpty( )	Private
NewIterator( )	Private
NewNode( )	Private
Remove( )	Private
RemoveAll( )	Private
RemoveHead( )	Private
RemoveTail( )	Private
AcObjectArray
AddToTail( )	Callable
GetAt( )	Callable
GetCount( )	Callable
GetHead( )	Callable
GetTail( )	Callable
IsEmpty( )	Callable
New( )	Callable
NewIterator( )	Callable
Remove( )	Callable
RemoveAll( )	Callable
RemoveAt( )	Private
RemoveEmptyEntries( )	Private
RemoveTail( )	Callable
ResizeTo( )	Callable
SetAt( )	Callable
AcArrayIterator
GetNext( )	Callable
HasMore( )	Callable
IsDone( )	Callable
New( )	Callable
Restart( )	Callable
SkipForwardTo( )	Callable
AcIterator
Copy( )	Callable
GetNext( )	Callable
HasMore( )	Callable
IsDone( )	Callable
New( )	Private
Restart( )	Callable
SkipForwardTo( )	Callable
SkipTo( )	Callable
AcSingleListIterator
Copy( )	Private
GetNext( )	Private
HasMore( )	Private
New( )	Private
Restart( )	Private
SkipForwardTo( )	Private


Data stream classes and methods

Use data stream classes and methods to work with data rows, data sources, and filters.

Class or method	Classification
AcDataRow
BuildBinding( )	Private
GetValue( )	Callable
OnRead( )	Overridable
AcDataAdapter
AddRow( )	Callable
AddSortKey( )	Callable
CanSeek( )	Overridable
CanSortDynamically( )	Overridable
CloseConnection( )	Overridable
Fetch( )	Overridable
Finish( )	Overridable
FlushBuffer( )	Callable
FlushBufferTo( )	Overridable
GetConnection( )	Callable
GetPosition( )	Callable
IsStarted( )	Callable
NewConnection( )	Overridable
NewDataRow( )	Overridable
OpenConnection( )	Overridable
Rewind( )	Callable
SeekBy( )	Callable
SeekTo( )	Overridable
SeekToEnd( )	Callable
SetConnection( )	Callable
Start( )	Overridable
AcDataSource
Finish( )	Overridable
HasFetchedLast( )	Callable
Start( )	Overridable
AcDatabaseSource
BindDataRow( )	Overridable
BindStaticParameters( )	Overridable
Fetch( )	Overridable
Finish( )	Callable
GetCursor( )	Callable
GetDBConnection( )	Callable
OpenCursor( )	Callable
AcSqlQuerySource
AddSortKey( )	Callable
AdhocToSQL( )	Callable
CanSortDynamically( )	Overridable
GetStatementText( )	Callable
ObtainSelectStatement( )	Overridable
SetAdHocParameter( )	Callable
SetupAdHocParameters( )	Overridable
Start( )	Overridable
AcStoredProcedureSource
No Methods defined
AcDataFilter
No Methods defined
AcSingleInputFilter
Fetch( )	Overridable
Finish( )	Overridable
NewInputAdapter( )	Overridable
SetInput( )	Callable
Start( )	Overridable
AcMemoryBuffer
AddRowToBuffer( )	Callable
CanSeek( )	Callable
Fetch( )	Overridable
FlushBufferTo( )	Callable
GetBufferCount( )	Callable
GetBufferStart( )	Callable
New( )	Overridable
SeekTo( )	Callable
Start( )	Overridable
AcRecordBuffer
No Methods defined
AcMemoryDataSorter
Compare( )	Overridable
CompareKeys( )	Callable
Sort( )	Private
SortArray( )	Private
Start( )	Overridable
AcMultipleInputFilter
Finish( )	Overridable
New( )	Overridable
NewInputAdapter( )	Overridable
Start( )	Overridable


Internal tools classes and methods

Use internal tools classes and methods to customize processing.

Class or method	Classification
AcPopupMenu
AddCascade( )	Overridable
AddItem( )	Overridable
AddSeparator( )	Overridable
CheckMenuItem( )	Callable
Delete( )	Private
EnableMenuItem( )	Callable
MakeMenu( )	Overridable
New( )	Private
Run( )	Callable
AcReportController
AttachReport( )	Overridable
AttachToThisReport( )	Overridable
FollowLink( )	Overridable
ShowNextPage( )	Callable
ShowPage( )	Callable
ShowPrevPage( )	Callable
AcReportView
AddMenuItem( )	Overridable
CreatePopupMenu( )	Overridable
DeselectAll( )	Private
DisplayHelp( )	Private
DisplayPage( )	Private
EndSelectionScan( )	Callable
FinishView( )	Private
GenerateHTML( )	Private
GenerateHTMLforComponent( )	Private
GetCurrentPageIndex( )	Private
GetNextSelection( )	Callable
GetPageCount( )	Private
GetPageByIndex( )	Private
GetSelectionCount( )	Callable
IsLandscape( )	Private
IsNextPageOK( )	Private
IsPageOK( )	Private
IsPrevPageOK( )	Private
IsSelected( )	Private
New( )	Private
NewMenu( )	Private
OnNewPage( )	Overridable
OnShowPage( )	Overridable
OnPrintPage( )	Overridable
PrintPage( )	Private
PrintPages( )	Callable
PrintAllPages( )	Callable
SelectComponent( )	Private
ShowFirstPage( )	Private
ShowLastPage( )	Private
ShowNextPage( )	Private
ShowPageByIndex( )	Private
ShowPreviousPage( )	Private
StartSelectionScan( )	Callable
StartView( )	Private
AcDisplayVisitor
CanRender( )	Private
VisitBaseFrame( )	Private
VisitCurrencyControl( )	Private
VisitDateTimeControl( )	Private
VisitDoubleControl( )	Private
VisitEllipseControl( )	Private
VisitFlow( )	Private
VisitFrame( )	Private
VisitGraph( )	Private
VisitHtmlObjectControl( )	Private
VisitIntegerControl( )	Private
VisitLabelControl( )	Private
VisitLineControl( )	Private
VisitOLEContainerControl( )	Private
VisitRectangle( )	Private
VisitSubpage( )	Private
AcVisitor
VisitBaseFrame( )	Overridable
VisitBasePage( )	Overridable
VisitComponent( )	Overridable
VisitConditionalSection( )	Overridable
VisitContents( )	Overridable
VisitControl( )	Overridable
VisitCurrencyControl( )	Overridable
VisitDataControl( )	Overridable
VisitDataFrame( )	Overridable
VisitDataSection( )	Overridable
VisitDateTimeControl( )	Overridable
VisitDetailGraph( )	Overridable
VisitDoubleControl( )	Overridable
VisitEllipseControl( )	Overridable
VisitFlow( )	Overridable
VisitFrame( )	Overridable
VisitGraph( )	Overridable
VisitGroupSection( )	Overridable
VisitHLCGraph( )	Overridable
VisitHtmlAppletControl( )	Overridable
VisitHtmlFrame( )	Overridable
VisitHtmlFrameControl( )	Overridable
VisitHtmlImageControl( )	Overridable
VisitHtmObjectControl( )	Overridable
VisitHtmlPlugInControl( )	Overridable
VisitHtmlReport( )	Overridable
VisitHtmlRuleControl( )	Overridable
VisitHtmlTableSection( )	Overridable
VisitImageControl( )	Overridable
VisitIntegerControl( )	Overridable
VisitLabelControl( )	Overridable
VisitLeftRightPageList( )	Overridable
VisitLinearFlow( )	Overridable
VisitLineControl( )	Overridable
VisitOleControl( )	Overridable
VisitOleContainerControl( )	Overridable
VisitPage( )	Overridable
VisitPageList( )	Overridable
VisitParallelSection( )	Overridable
VisitRectangleControl( )	Overridable
VisitReport( )	Overridable
VisitReportSection( )	Overridable
VisitSequentialSection( )	Overridable
VisitSimplePageList( )	Overridable
VisitSubpage( )	Overridable
VisitSummaryGraph( )	Overridable
VisitTextControl( )	Overridable
VisitTitleBodyPageList( )	Overridable
VisitVisualComponent( )	Overridable


AFC data types

The AFC framework defines the following data types.

AcBitmapStyle

AcColor

AcCursorShape

AcFlowPlacement

AcFont

AcGraphAxisStyle

AcGraphBarGrouping

AcGraphBarOrientation

AcGraphBorderStyle

AcGraphLabelStyle

AcGraphLegendPosition

AcGraphLineStyle

AcGraphPoint

AcGraphPointLabelStyle

AcGraphTickStyle

AcGraphType

AcGraphXAxisPosition

AcGraphXValueSet

AcGraphYAxisPosition

AcGraphYOrientation

AcHtmlBackgroundStyle

AcHtmlFrameStyle

AcHtmlHorizontalAlignment

AcHtmlImageAlignment

AcHtmlImageMapType

AcHtmlPlugInUnits

AcHtmlTableCaptionStyle

AcHtmlTableStyle

AcHtmlTextAlignment

AcHtmlTextVertAlignment

AcHtmlTocStyle

AcHtmlUnits

AcLinePen

AcLineStyle

AcMargins

AcPoint

AcRectangle

AcRounding

AcShadow

AcShiftKeyState

AcSize

AcTextClipStyle

AcTextJustify

AcTextPlacement

AcTextVerticalPlacement

AcTwips

AcWordWrapStyle

See also

About the AFC data types


About the AFC data types

AFC data types are either typedefs or structures.

•	A typedef is an alias for the Basic data types, typically an Integer. The AFC framework uses typedefs to create a type that has additional rules beyond what a simple Integer provides. These rules include a limited range, special display formatting, and a set of related constants. For example, colors (AcColor) can be in the range 0 to hexadecimal FFFFFF.

•	A structure is a group of variables that together describe a property. The structure members can be Basic data types, such as an Integer, or other AFC defined structures. In some cases structures are nested.

Some types are intended to be enumerations (enums). An enum is one whose value can only be one of the associated constants. For example, a Boolean can only be True or False. Other types can have constants also. In this case, the constant provides a convenient shorthand for certain values.


AcBitmapStyle

The AcBitmapStyle specifies how a bitmap is displayed.

Constant	Value	Description
StretchToFit	0	Stretches to fit (both horizontal and vertical)
KeepAspectRatio	1	Keeps aspect ratio and sizes the bitmap to fit within the control
KeepOriginal Size	2	Shows the original size and clips the parts of the bitmap that do not fit within the control


AcColor

The AcColor data type is an Integer that contains a color expressed as a standard Windows RGB value. The AFC supports the standard Windows 16 million colors. The AFC framework defines the following constants for common Windows colors.

Constant	RGB Value
Black	&H00
Blue	&HFF0000
Cyan	&HFFFF00
DarkGray	&H404040
Forest	&H7F00
Gray	&H808080
Green	&HFF00
LightGray	&HC0C0C0
Magenta	&HFF00FF
Maroon	&H7F
Navy	&H7F0000
Olive	&H7F7F
Purple	&H7F007F
Red	&HFF
Teal	&H7F7F00
White	&HFFFFFF
Yellow	&HFFFF
Considerations for HTML reports

AcColor adds a new color symbol for use with HTML reports.

Constant	Description
TransparentColor	Specifies that the object use the color previously specified in the HTML file. For example, if you create a table and you want the table background color to be the same as the background color of the report, specify TransparentColor as the table's background color


AcCursorShape

The AcCursorShape data type is an Integer that contains the cursor shape. The following constants define the cursor shape for AcCursorShape.

Constant	Description
ArrowCursor	Default arrow cursor
ActiveCursor	Actuate "active" cursor for elements that are selectable
IBeamCursor	Windows I-beam cursor
WaitCursor	Windows wait cursor (usually an hourglass)
CrossCursor	Windows cross cursor (cross-hair)
UpArrowCursor	Windows up-arrow cursor (vertical)
SizeCursor	Windows resize cursor (cross with arrows in 4 directions)
IconCursor	Windows icon cursor
SizeNWSE Cursor	Windows NWSE cursor (slanting top-left to bottom-right)
SizeNESW Cursor	Windows NESW cursor (slanting top-right to bottom-left)
SizeWECursor	Windows horizontal resize arrow
SizeNSCursor	Windows vertical resize arrow
SizeAllCursor	NT cursor. Not available in Windows 3.1
NoCursor	NT No cursor (circle with backward slanting bar). Not available in Windows 3.1
AppStarting Cursor	NT Application starting cursor (arrow with hour glass). Not available in Windows 3.1
HandCursor	Actuate hyperlink cursor, shaped like a hand
QuestionCursor	Actuate help cursor, shaped like a question mark


AcFlowPlacement

The AcFlowPlacement data type is an Integer that describes how a frame appears within a flow when the frame is narrower than the flow.

Constant	Value	Description
FlowAlignCenter	1	Aligns a frame in the center of a flow
FlowAlignLeft	0	Aligns a frame to the left of a flow
FlowAlignRight	2	Aligns a frame to the right of a flow
FlowAlign Custom	3	Aligns frames in the flow at the position given by the frame's Position.X member


AcFont

The AcFont data type is a structure that describes a font in a device-independent way.

Member Name	Type	Description
Bold	Boolean	True = bold text
Color	AcColor	Color of the text
FaceName	String	Font name of the text
Italic	Boolean	True = italic text
Size	Float	Size of the text in points
StrikeThrough	Boolean	True = strike through text
Underline	Boolean	True = underlined text
Considerations for HTML reports

HTML provides limited support for choosing fonts.  AFC maps the AcFont type into corresponding HTML font commands as shown in the following table.

Font Property	HTML Tag	Comments
FaceName	<Font Face= "name"> <PlainText>  </PlainText >	Sets the font face name. There are two special names: Default, Fixed that map to the browser's default fonts
Bold	<B> </B>	Sets bold text
Color	<Font Color= color>	Sets the font color
Italic	<I> </I>	Sets italic text
Size	<Font Size=n>	Sets the font size.  The size is set in the Designer in points, but is mapped to a relative size when the report generates HTML
StrikeThrough	<S> </S>	Sets strike-through text
Underline	<U> </U>	Sets underline text
In HTML, a page can set different font options independently, and the options remain in effect until changed later down the page.  In Actuate, each control has its own font specification.  Therefore, AFC generates a complete set of font commands for each individual control, and settings for one control do not affect adjacent controls.  In practice, to reduce the size of the generated report, AFC generates HTML for the font only when an attribute changes.


AcGraphAxisStyle

AcGraphAxisStyle is an Integer that specifies how to display the X-axis for graphs.

Constant	Value	Description
GraphZero Origin	0	Displays the X-axis originating with zero
GraphAuto Origin	1	Displays the X-axis originating with the smallest values present in the data set
GraphCustom Origin	2	Displays the X-axis according to values you specify


AcGraphBarGrouping

AcGraphBarGrouping is an Integer that specifies how bars are to be grouped in bar graphs.

Constant	Value	Description
GraphBarNo Grouping	0	Produces a bar graph with no grouping
GraphBarCluster	1	Produces a cluster bar graph
GraphBarStack	2	Produces a stacked bar graph
GraphBarStack Percentage	3	Produces a stacked percentage bar graph
GraphBar ClusterZ	4	Produces a three-dimensional cluster bar graph


AcGraphBarOrientation

AcGraphBarOrientation is an Integer that specifies the orientation for bar graphs.

Constant	Value	Description
GraphBarVertical	0	Produces a vertical bar graph
GraphBar Horizontal	1	Produces a horizontal left-based graph
GraphBarHori zontalReversed	2	Produces a horizontal right-based graph


AcGraphBorderStyle

AcGraphBorderStyle is an Integer that specifies the style of a title in a graph.

Constant	Value	Description
GraphNoBorder	0	Displays no border
GraphSolid Border	1	Displays a solid border
GraphDrop Shadow	2	Displays a shadow
GraphShadow AndBorder	3	Displays a shadow and border combination
GraphRaised Border	4	Displays a raised border
GraphLowered Border	5	Displays a sunken border


AcGraphLabelStyle

AcGraphLabelStyle is an Integer that specifies the source of axis labels.

Constant	Value	Description
GraphNoLabels	0	Displays no labels
GraphAuto Labels	1	Displays labels computed automatically
GraphCustom Labels	2	Displays custom labels based on the information you enter in the XLabelsList property
GraphExpression Labels	3	Displays labels computed from an expression you specify in the LabelExp property


AcGraphLegendPosition

AcGraphLegendPosition is an Integer that specifies the position of the legend within a graph.

Constant	Value	Description
GraphLegend None	0	Displays no legend
GraphLegend Top	1	Displays the legend at the top of the graph
GraphLegend TopRight	2	Displays the legend at the top right of the graph
GraphLegend TopLeft	3	Displays the legend at the top left of the graph
GraphLegend Left	4	Displays the legend at the left of the graph
GraphLegend Right	5	Displays the legend at the right of the graph
GraphLegend BottomLeft	6	Displays the legend at the bottom left of the graph
GraphLegend Bottom	7	Displays the legend at the bottom of the graph
GraphLegend BottomRight	8	Displays the legend at the bottom right of the graph


AcGraphLineStyle

AcGraphLineStyle is an Integer that specifies the style of the lines in a line graph.

Constant	Value	Description
GraphDefault Lines	0	Displays the graph using the default line styles
GraphPattern Lines	1	Displays the graph using the line styles defined in patterns
GraphThickLines	2	Displays the graph using thick line styles


AcGraphPoint

AcGraphPoint contains the data maintained for each data point in a graph.

Member Name	Type	Description
X	Double	The x-value of the data point
Y	Double	The y-value of the data point
Z	Double	The z-value of the data point
Label	String	The label associated with the data point


AcGraphPointLabelStyle

AcPointLabelStyle is an Integer that specifies how to display point labels for graphs.

Constant	Value	Description
GraphNoPoint Labels	0	No labels displayed
GraphTextLabels	1	Text labels displayed. Displays the string label associated with each point
GraphNumeric Labels	2	Numeric labels displayed. Displays the Y-value of the point adjacent to the point
GraphColored TextLabels	3	Text labels displayed in color. Displays the string label associated with each point
GraphColored NumericLabels	4	Numeric labels displayed in color. Displays the Y-value of the point adjacent to the point


AcGraphTickStyle

AcGraphTickStyle is an Integer that specifies the tick marks for a graph axis.

Constant	Type	Description
GraphNoTicks	0	Displays no tick marks
GraphAutoTicks	1	Displays tick marks computed automatically
GraphCustom Ticks	2	Displays custom tick marks


AcGraphType

The AcGraphType is an Integer that specifies the graph type.

Constant	Value	Description
Graph2DArea	1	Renders a two-dimensional area graph
Graph3DArea	2	Renders a three-dimensional area graph
Graph2DBar	3	Renders a two-dimensional bar graph
Graph3DBar	4	Renders a three-dimensional bar graph
Graph2DPie	5	Renders a two-dimensional pie graph
Graph3DPie	6	Renders a three-dimensional pie graph
GraphCandle Stick	7	Renders a candlestick graph
GraphHLC	8	Renders a High-Low-Close graph.
GraphLine	9	Renders a line graph
GraphOHLC	10	Renders an Open-High-Low-Close graph
GraphScatter	11	Renders a scatter plot graph
GraphTape	12	Renders a tape graph


AcGraphXAxisPosition

AcGraphXAxisPosition is an Integer that specifies where to display the X-axis.

Constant	Value	Description
GraphXAxis Auto	0	Dynamically determines where to display the X-axis
GraphXAxisTop	1	Always displays the X-axis at the top of the graph
GraphXAxis Bottom	2	Always displays the X-axis at the bottom of the graph


AcGraphXValueSet

AcGraphXValueSet is an Integer that specifies the number of X-values provided.

Constant	Value	Description
GraphDefaultX Values	0	X-values are implied by graph type
GraphXValues PerDataSet	1	There is one set of X-values shared by all points
GraphXValue PerPoint	2	Each point has its own X-value


AcGraphYAxisPosition

AcGraphYAxisPosition is an Integer that specifies where to display the Y-axis.

Constant	Value	Description
GraphYAxisAuto	0	Dynamically determines where to display the Y-axis
GraphYAxisLeft	1	Always displays the Y-axis at the left of the graph
GraphYAxis Right	2	Always displays the Y-axis at the right of the graph


AcGraphYOrientation

AcGraphYOrientation is an Integer that specifies the orientation of the graph Y-Axis title.

Constant	Value	Description
GraphYLabelUp	0	Displays the Y-axis title vertically, from bottom to top
GraphYLabel Horiz	1	Displays the Y-axis title horizontally
GraphYLabel Down	2	Displays the Y-axis title vertically, from top to bottom


AcHtmlBackgroundStyle

The AcHtmlBackgroundStyle sets the style of an image that appears as the background of a web page.

Constant	HTML Option	Description
ScrollableBack ground	(Default)	Scrolls the background image with the contents of the report
FixedBack ground	BGProperties= Fixed	Keeps the background image in a fixed position as the contents of the report scroll


AcHtmlFrameStyle

The AcHtmlFrameStyle type enumerates the options for formatting text in an HTML report.

Constant	HTML Option	Description
HtmlBodyText	(Default)	Default text style
HtmlHeading1	H1	Level 1 heading
HtmlHeading2	H2	Level 2 heading
HtmlHeading3	H3	Level 3 heading
HtmlHeading4	H4	Level 4 heading
HtmlHeading5	H5	Level 5 heading
HtmlHeading6	H6	Level 6 heading
HtmlHeading7	H7	Level 7 heading
HtmlHeading8	H8	Level 8 heading
HtmlHeading9	H9	Level 9 heading
HtmlDefinition List	DL	Definition list
HtmlBulletedList	UL	Bulleted list.  Items are prefixed by a bullet character
HtmlOrderedList	OL	Ordered list.  Items are prefixed by a number
HtmlTable	<Table...>	The frame is arranged using an HTML table to preserve some of the two-dimensional flavor of an Actuate frame


AcHtmlHorizontalAlignment

The AcHtmlHorizontalAlignment type enumerates the options for aligning objects on the horizontal plane.

Constant	HTML Option	Description
HtmlHoriz Default	(Default)	Aligns the objects according to the default alignment specified by the browser
HtmlLeftAlign	align=left	Aligns the object with the left margin
HtmlCenter Align	align=center	Centers the object horizontally within the margins
HtmlRightAlign	align=right	Aligns the object with the right margin


AcHtmlImageAlignment

The AcHtmlImageAlignment type enumerates the options for aligning images or applets relative to surrounding text.

Constant	HTML Option	Description
HtmlAlignImage None	(Default)	Uses the default image alignment
HtmlAlignImage Top	Align=top	Aligns the top of the image with the top of the tallest image, item, or character in the surrounding text
HtmlAlignImage Middle	Align=middle	Aligns the center of the image with the baseline of the surrounding text
HtmlAlignImage Bottom	Align=bottom	Aligns the bottom of the image with the bottom of the lowest descending image, item, or character in the surrounding text
HtmlAlignImage TextTop	Align=texttop	Aligns the top of the text with the top of the tallest character in surrounding text
HtmlAlignImage AbsMiddle	Align= absmiddle	Aligns the center of the image with the center of surrounding text
HtmlAlignImage AbsBottom	Align= absbottom	Aligns the center of the image with the bottom of the lowest descender in surrounding text
HtmlAlignImage Left	Align=left	Left-justifies the image. Surrounding text flows around the image
HtmlAlignImage Right	Align=right	Right-justifies the image. Surrounding text flows around the image
HtmlAlignImage Center		Centers the image on a line that contains only the image


AcHtmlImageMapType

The AcHtmlImageMapType type enumerates the options for associating an image map with an image in an HTML report

Constant	HTML Option	Description
HtmlNoImage Map	N/A	No image map for an image
HtmlClientSide Map	IsMap Map=filename	The image uses a client-side image map
HtmlServerSide Map	IsMap	The image uses a server-side image map
.


AcHtmlPlugInUnits

The AcHtmlPlugInUnits type defines how the size of plug-in windows are measured.

Constant	HTML Option	Description
HtmlPlugIn Percent	attrib=nn%	Measurements are expressed as a percent of the overall height or width
HtmlPlugInEns	attrib= nn	Measurements are expressed in units of "ens", the width of an "n" in the current font


AcHtmlTableCaptionStyle

The AcHtmlTableCaptionStyle type specifies the placement of a table caption.

Constant	HTML Option	Description
HtmlNoCaption	N/A	The table has no caption
HtmlCaption Above	<Caption VAlign=top>	Places a caption above an HTML table
HtmlCaption Below	<Caption VAlign=bottom>	Places a caption below an HTML table


AcHtmlTableStyle

The AcHtmlTableStyle type specifies how to create a table in an HTML report.

Constant	Description
HtmlAutomatic Table	The AFC decides how to create a table (default behavior). If the total number of frames in the section is less than a maximum (the default is 500), AFC creates a table for the section.
HtmlNotTable	Do not create a table for the section
HtmlCreateTable	Create a table for the section, regardless of the number of frames in the section


AcHtmlTextAlignment

The AcHtmlTextAlignment type enumerates the options for aligning text horizontally in an HTML frame.

Constant	HTML Option	Description
HtmlTextAlign Left	(Default)	Left justifies text in a frame
HtmlTextAlign Center	<Center>	Centers the text in a frame


AcHtmlTextVertAlignment

The AcHtmlTextVertAlignment type specifies how objects are aligned vertically within a table cell.

Constant	HTML Option	Description
HtmlTextVert Default	(Default)	Aligns the objects according to the default alignment specified by the browser
HtmlTextTop	Valign=top	Aligns the object with the top of the surrounding text or space
HtmlTextMiddle	Valign=center	Centers the object vertically
HtmlTextBottom	Valign=bottom	Aligns the object with the bottom edge of the surrounding text or space
HtmlTextBase line	Valign=baseline	Aligns the object with the baseline of surrounding text


AcHtmlTocStyle

The AcHtmlTocStyle type enumerates the options for including a TOC in an HTML report.

Constant	HTML Option	Description
HtmlNoToc	N/A	The report has no TOC
HtmlTocIn Header	N/A	Places the TOC at the top of the report
HtmlTocInFrame	N/A	Places the TOC in a separate HTML frame


AcHtmlUnits

The AcHtmlUnits type defines how object sizes are measured.

Constant	HTML Option	Description
HtmlPercent	attrib=nn%	Measurements are expressed as a percent of the overall height or width
HtmlPixels	attrib= nn	Measurements are expressed in absolute pixels


AcLinePen

The AcLinePen data type is an Integer that specifies the style of line to draw. Note that although these mimic the Windows line styles, they are not meant to duplicate their values or have a direct numeric mapping to Windows styles.

Constant	Value	Description
DashDotDotLine	4	Draws a line in the format: ----- -- -- ----- -- --
DashDotLine	3	Draws a line in the format: ----- -- ----- -- ----- --
DashLine	1	Draws a dashed line
DotLine	2	Draws a dotted line
DoubleLine	9	Draws a double solid line
InsideFrame Border	6	Draws a solid line inside the frame or control
NullLine	5	Does not draw a line
ShortDotLine	8	Draws a line using very small dots
SingleLine	0	Draws a single solid line


AcLineStyle

The AcLineStyle data type is a structure that describes characteristics of a line.

Member Name	Type	Description
Color	AcColor	The color of the line
Pen	AcLinePen	The style of the line
Width	AcTwips	The width of the line in twips


AcMargins

The AcMargins data type is a structure that describes the amount of space to reserve outside of the enclosing rectangle.

Member Name	Type	Description
Bottom	AcTwips	The amount of space, measured in twips, to reserve along the bottom of a rectangle
Left	AcTwips	The amount of space, measured in twips, to reserve along the left of a rectangle
Right	AcTwips	The amount of space, measured in twips, to reserve along the right of a rectangle
Top	AcTwips	The amount of space, measured in twips, to reserve along the top of a rectangle


AcPoint

The AcPoint data type is a structure that describes the offset coordinates from some origin as defined by the client.

Member Name	Type	Description
X	AcTwips	The horizontal location of the point measured from the left of the origin
Y	AcTwips	The vertical location of the point measured from the top of the origin


AcRectangle

The AcRectangle data type is a structure that describes a rectangle relative to the origin of an enclosing rectangle by giving the bounding points (corners) of the rectangle.

Member Name	Type	Description
Bottom	AcTwips	The location of the bottom of the rectangle measured relative to the top of the enclosing rectangle
Left	AcTwips	The location of the left of the rectangle measured relative to the left of the enclosing rectangle
Right	AcTwips	The location of the right of the rectangle measured relative to the left of the enclosing rectangle
Top	AcTwips	The location of the top of the rectangle measured relative to the top of the enclosing rectangle


AcRounding

The AcRounding data type is a structure that describes the characteristics of a rectangle with round corners.

Member Name	Type	Description
X	AcTwips	The focus of the rounding, measured in twips, from the left and right side of the rectangle
Y	AcTwips	The focus of the rounding, measured in twips, from the top and bottom of the rectangle


AcShadow

The AcShadow data type is a structure that describes the format of a shadow for a rectangle.

Member Name	Type	Description
Color	AcColor	Shadow color
Height	AcTwips	Height of the shadow in twips
Width	AcTwips	Width of the shadow in twips


AcShiftKeyState

The AcShiftKeyState data type is an Integer that contains the flags for keys pressed during mouse actions. The settings in AcShiftKeyState match the settings of the Shift bit field used in Visual Basic for MouseUp and MouseDown events. The actual value can be a combination of the values below, depending on the keys pressed.

Constant	Value	Description
NoKeys	0	No modifier keyboard keys were pressed when the mouse event occurred
ShiftKey	1	The Shift key was pressed when the mouse event occurred
ControlKey	2	The Control key was pressed when the mouse event occurred
AltKey	4	The Alt key was pressed when the mouse event occurred


AcSize

The AcSize data type is a structure that describes the width and height of a rectangle.

Member Name	Type	Description
Height	AcTwips	The vertical size of the rectangle in twips
Width	AcTwips	The horizontal size of the rectangle in twips


AcTextClipStyle

The AcTextClipStyle data type is an integer that specifies how to handle text that is too long for its enclosing rectangle. Leading truncation removes the first part of the string, while trailing truncation removes the end part. There is also an option to use an ellipsis to show truncation. Applies only to single-line controls.

Constant	Value	Description
ClipLeading	1	Clips the leftmost characters of the text
ClipTrailing	0	Clips the rightmost characters of the text.
ShowOverflow Char	2	Appends an ellipsis (...) to the end of the clipped text


AcTextJustify

The AcTextJustify data type is an Integer that specifies how text is aligned.

Constant	Value	Description
TextAlignCenter	1	Aligns text in the center of the control
TextAlignLeft	0	Aligns text at the left of the control
TextAlignRight	2	Aligns text at the right of the control


AcTextPlacement

The AcTextPlacement data type is a structure that describes the placement of text in a frame or control.

Member Name	Type	Description
Clip	AcTextClipStyle	Defines how to clip text that is too large to fit into the control. Applies to single-line controls only
Ellipsis	Boolean	If set to True, places ellipses in a text control if the value is truncated. Applies to single-line controls only
FillPattern	String	Determines the fill pattern to use if there is extra room in the control's container
Horizontal	AcTextJustify	Defines horizontal text justification
MultiLine	Boolean	Determines whether the control contains one or more lines of text
Vertical	AcTextVertical Placement	Determines vertical text placement. Applies to single-line controls only
WordWrap	AcWordWrap Style	Defines how to wrap text from one line to the next. Applies to multi-line controls only. Values are: 0 = Word wrap 2 = Character wrap 3 = Truncate lines


AcTextVerticalPlacement

The AcTextVerticalPlacement data type is an Integer that specifies how single lines of text align vertically within the enclosing rectangle.

Constant	Value	Description
TextAlignBottom	2	Aligns text at the bottom of a control
TextAlignMiddle	1	Aligns text in the vertical middle of a control
TextAlignTop	0	Aligns text at the top of a control


AcTwips

The AcTwips data type is an Integer that specifies the basic unit of measurement in the AFC framework.

Constant	Value	Description
OneCM	567	A distance of 1 centimeter
OneInch	1440	A distance of 1 inch
OneMM	57	A distance of 1 millimeter
OnePoint	20	A distance of 1 printer's  point (1/20")


AcWordWrapStyle

The AcWordWrapStyle data type is an Integer that specifies the actions for lines in a multi-line control when a line is longer than the size of the control.

Constant	Value	Description
ObsoleteWord Wrap	1	Placeholder
TextCharacter Wrap	2	Wraps text from one line to the next breaking the text at a character boundary
TextTruncate Lines	3	Truncates any lines that do not fit
TextWordWrap	0	Wraps text from one line to the next breaking the text at a word boundary


AFC classes

This section provides an alphabetical listing of the Actuate Foundation Classes. Each class entry includes a general description of the class and a summary of its variables, properties, and methods followed by an alphabetical listing of methods for that class.

Be aware that the class documentation generally does not include repeated descriptions of inherited variables, properties, and methods. For example, the OnRow( ) method is described only in the AcReportComponent base class where the method is defined.

A method, however, is described in a superclass as well as its subclass if the implementation details are significantly different or enhanced. For example, BuildFromRow( ) is described in several class entries, including AcReportComponent, AcReportSection, AcDataFrame, and AcDataControl.


Class AcBaseFrame

Methods

An abstract base class that defines the core logic common to pages and frames.

Description

AcBaseFrame is the abstract base class for pages and frames. It provides the core logic for creating and working with contents in a page or a frame. The contents of a page can include flows and controls, and the contents of a frame, other frames and controls.

The framework instantiates the contents of a frame or page using Start( ). Start( ), in turn, calls MakeContents( ) to instantiate each of the contents in the order in which they were added in the Design Editor.

AcBaseFrame defines methods for accessing the contents of a frame or page. The FindContentByClass( ) method locates the specified content in a frame or a page, and the GetControlValue( ) method returns the value of any data control contained in a frame.

AcBaseFrame also defines page-specific methods, such as GetPageIndex( ) and GetPageNumber( ), that are not applicable to frames. If you call these methods in a frame, Actuate displays an error.

Factory protocol

Method	Task
Start( )	Instantiates and starts the contents of the frame or the page.
BuildFromRow( )	Populates the contained frames, graphs, and controls with data.
Finish( )	Finishes each of the content objects.
Subclassing AcBaseFrame

Because AcBaseFrame is an abstract base class, you generally do not derive directly from it.

Variables

Variable	Type	Description
BackgroundColor	AcColor	The color with which the frame is filled before displaying its contents. The default is TransparentColor.
BackgroundIsClear	Boolean	True indicates the background is clear.
Border	AcLineStyle	The style, thickness, and color of the border. The default is no border.
Properties

Property	Type	Description
BackgroundColor	AcColor	The color with which the frame is filled before displaying its contents. The default is TransparentColor.
BackgroundIsClear	Boolean	True indicates the background is clear.
Border	AcLineStyle	The style, thickness, and color of the border. The default is no border.
Methods

Method	Type	Description
BindToFlow( )	N/A	Called when the framework places the frame into a flow on the page.
Build( )	N/A	Calls the Build( ) method of each content component.
FindContentByClass( )	N/A	Locates one of the frame's contents given the class name of that content.
Finish( )	N/A	Finishes the contents of the frame.
GetControlValue( )	Variant	Returns the value of a control within the frame.
GetPageIndex( )	Integer	Returns the page index for a page.
GetPageNumber( )	String	Returns the formatted page number for a page.
MakeContents( )	N/A	Creates the contents of the frame or page based on the structure references defined in the structure pane.
RebindToFlow( )	N/A	Called by the framework for controls that appear within a subpage.
Start( )	N/A	Calls MakeContents( ) to create the contents of the frame or page.


Methods for class AcBaseFrame

AcBaseFrame::AddContent method

AcBaseFrame::BindToFlow method

AcBaseFrame::Build method

AcBaseFrame::FindContentByClass method

AcBaseFrame::Finish method

AcBaseFrame::GetControlValue method

AcBaseFrame::GetPageIndex method

AcBaseFrame::GetPageNumber method

AcBaseFrame::MakeContents method

AcBaseFrame::RebindToFlow method

AcBaseFrame::Start method


AcBaseFrame::AddContent method

See also

Adds a component to a frame.

Syntax

Sub AddContent( component As AcReportComponent )

component

The component to add to the frame.

Description

If you want to conditionally instantiate a control, call AddContent( ) from within MakeContents( ) to add the content to the frame or page. MakeContents( ) instantiates all the contents in a frame or page.


See also

AcBaseFrame::MakeContents method


AcBaseFrame::BindToFlow method

Example

Called when the framework places the frame into a flow on the page.

Syntax

Sub BindToFlow( flow As AcFlow )

flow

The flow that contains the component.

Description

The framework calls BindToFlow( ) for a frame when the framework places the frame into a flow on the page. You can override this method to perform actions based on where the control is in a flow. For example, the flow can keep track of an alternating color for its frames, and the frame can ask the flow for the proper color in this method.

If you override this method, you must call Super::BindToFlow( ).


Example

The following example shows how you override BindToFlow( ) to assign a different color to every alternate frame in a flow. The code example assumes the following variables have been declared for the frame: AlternateColor, AlternateLines, MostRecentContainer, MostRecentFlow, and RowNumber.

Sub BindToFlow( flow As AcFlow )

    Super::BindToFlow( flow )

' If the current flow is different from the

' previous flow, then reset the color.

    If Not MostRecentFlow Is flow Then

        RowNumber = 0

Set MostRecentFlow = flow

    End If

' If the container is different, this frame is for

' a different group than the previous one; therefore,

' reset the color.

If Not MostRecentContainer Is Container Then

RowNumber = 0

Set MostRecentContainer = Container

End If

' Choose one of the two colors. AlternateLines and AlternateColor
' are user-defined properties that can be set in the Component Editor

    RowNumber = RowNumber + 1

    If RowNumber > AlternateLines * 2 Then

        RowNumber = 1

    End If

    If RowNumber > AlternateLines Then

        BackgroundColor = AlternateColor

    End If

End Sub


AcBaseFrame::Build method

See also

Calls the Build( ) method on each of the controls that the frame or page contains.

Syntax

Sub Build( )

Description

The frame's Build( ) method is called (instead of the BuildFromRow( ) method) by its container's Build( ) method when the frame is placed in a slot where it does not receive any data rows. The following list includes some of the situations when the frame's Build( ) method is called:

•	The frame is the top-level component within the report component (a subclass of AcReport).

•	The frame is placed in a sequential or conditional section that is placed directly within the report component.

•	The frame is placed directly on a page.

•	The frame is nested within any of the frames described in the previous bullets.

The frame's Build( ) method, in turn, calls the Build( ) method for each of the controls it contains.

You can override a frame's or a page's Build( ) method to perform custom processing, such as conditionally adding or deleting frame or page contents, or setting the values or properties of the contents.


See also

AcDataControl::Build method

AcDataFrame::BuildFromRow method

AcReportComponent::Build method


AcBaseFrame::FindContentByClass method

Example   See also

Locates a content component given the class name of that component.

Syntax

Function FindContentByClass( className As String ) As AcVisualComponent

className

The class name of the component to find. You can specify a fully qualified class name or just the class name. For example, you can use the names MyDesign::MyFrame::MyControl, MyFrame::MyControl, or just MyControl to find a control called MyControl. If you want to specify the control as a global class, prefix the name with a double colon: ::GlobalControl.

Description

You can uniquely identify a content within a frame or page by its class name. This capability makes it easy to access and manipulate contents, for example, conditionally add or remove controls in a frame. To access a content component, call the FindContentByClass( ) method.

Return value

A reference to the component, if found.

Nothing if the component was not found.


Example

In the following example, FindContentByClass( ) is used to find a control on a page. Once found, the control is deleted from the first page.

' First, override the page's GetContentIterator( ) method to iterate
' over the contents in the page.

Function GetContentIterator( ) As AcIterator

Dim contents As AcOrderedCollection

Set contents = GetContents( )

If contents Is Nothing Then

Set contents = New AcSingleList

End If

Set GetContentIterator = contents.NewIterator( )

End Function

' Override the page's Finish( ) method to remove the control
' from the first page.

Sub Finish( )

Super::Finish( )

Dim iter As AcIterator

Dim content As AcReportComponent

Set iter = GetContentIterator( )

Do while iter.HasMore()

Set content = iter.GetNext( )

Dim control As AcControl

Set control = FindContentByClass( "LabelControl" )

If GetPageIndex( ) = 1 Then

GetContents( ).Remove(control)

End If

Loop

End Sub


See also

AcBaseFrame::MakeContents method


AcBaseFrame::Finish method

Example

Performs cleanup work for the frame.

Syntax

Sub Finish( )

Description

The Finish( ) method performs cleanup work for the frame. It calls Finish( ) on each of the contents of the frame.

You can override Finish( ) to do special processing such as moving the position of a control once all the data has been received and all the controls' values have been set.


Example

The following example shows how to export processed results to a spreadsheet such as Excel. To view the code used in this example in a fuller context, open Examples\GOTOEXEL3.ROD, highlight the Frame, and examine its Finish( ) method.

The code example appears in the Finish() method of a frame. This example writes data to a target file that you previously opened in the Start( ) method of the component that contains the frame.

This target file is opened and identified in the code as #rptChannel and named GO2EXCEL.TXT in the context example. GO2EXCEL.TXT is a comma-delimited text file. Most spreadsheet or database programs can import text files.

In the context example, the frame contains a calculated control, CalcControl1, which takes the price of a scoop of ice cream, multiplies by the number of scoops sold, and displays the result.

The code writes the calculated value to the text file, along with the values of all the other controls in the frame.

Sub Finish( )

    Super::Finish( )

    ' Insert your code here

Dim flavorControlVar As AcTextControl

Dim colorControlVar As AcTextControl

Dim ingredsControlVar As AcTextControl

Dim quantityControlVar As AcIntegerControl

Dim priceControlVar As AcCurrencyControl

Dim calcControlVar As AcCurrencyControl

Dim flavorOut As String

Dim colorOut As String

Dim ingredsOut As String

Dim quantityOut As Integer

'Use Double so output does not appear in quotes

Dim priceOut As Double

Dim calcOut As Double

Set flavorControlVar = FindContentByClass( "flavorControl" )

Set colorControlVar = FindContentByClass( "colorControl" )

Set ingredsControlVar = FindContentByClass( "ingredientsControl" )

Set quantityControlVar = FindContentByClass( "quantityControl" )

Set priceControlVar = FindContentByClass( "PriceControl" )

Set calcControlVar = FindContentByClass( "CalcControl1" )

flavorOut = flavorControlVar.GetValue()

colorOut = colorControlVar.GetValue()

ingredsOut = ingredsControlVar.GetValue()

quantityOut = quantityControlVar.GetValue()

priceOut = priceControlVar.GetValue()

calcOut = calcControlVar.GetValue()

Write #rptChannel, flavorOut, colorOut, ingredsOut, quantityOut, priceOut, calcOut

End Sub


AcBaseFrame::GetControlValue method

See also

Returns the value of a specified data control within the frame.

Syntax

Function GetControlValue( controlName As String ) As Variant

controlName

The name of the control for which you want the value.

Description

Use GetControlValue( ) method to get the value of a specified data control within a frame. You specify the control giving either just the last part of the control's name (such as PriceControl), or using its fully qualified name (such as OrdersReport::ItemFrame::PriceControl). GetControlValue( ) finds the control, then calls that control's GetValue( ) method to obtain the value.

If you call this method from BuildFromRow( ), then you must be aware of the order in which controls are built. Generally, the controls of a frame are built in the same order that they appear in the structure pane. If you call GetControlValue( ) to get the value of a control that has not been created, GetControlValue( ) returns Null.

Return value

The value of the control if the control exists.

Null if the control does not exist.


See also

AcControl::GetControlValue method


AcBaseFrame::GetPageIndex method

Example   See also

Returns the page index.

Syntax

Function GetPageIndex( ) As Integer

Description

The page index is a number, starting with 1, that identifies the position of the page in the report. Call GetPageIndex( ) from a page only; this method does not apply to frames.

The page index is set after the page's Start( ) method has executed. If you write code that relies on the page index value, place that code in a method, such as Build( ) or Finish( ), that is called after Start( ).

Return value

The page index of a page.


Example

The following example shows how a flow on the first page is changed to teal while the flow on the other pages use the color set at design time. GetContentIterator( ) is overridden to create an iterator to find the flow. Build( ) is overridden to change the color of the flow. GetPageIndex( ) is used to identify the first page.

' First, override the page's GetContentIterator( ) method to iterate
' over the contents in the page.

Function GetContentIterator( ) As AcIterator

Dim contents As AcOrderedCollection

Set contents = GetContents( )

If contents Is Nothing Then

Set contents = New AcSingleList

End If

Set GetContentIterator = contents.NewIterator( )

End Function

' Override the page's Build( ) method to find the flow and change
' its background color to teal only on the first page.

Sub Build( )

    Super::Build( )

    Dim iter As AcIterator

Dim content As AcReportComponent

Set iter = GetContentIterator( )

Do while iter.HasMore( )

Set content = iter.GetNext( )

Dim flow As AcFlow

Set flow = FindContentByClass( "Flow" )

If GetPageIndex( ) = 1 Then

Flow.BackgroundColor = teal

End If

Loop

End Sub


See also

AcBaseFrame::GetPageNumber method


AcBaseFrame::GetPageNumber method

See also

Returns the page number.

Syntax

Function GetPageNumber( ) As String

Description

The page number is a formatted string that represents the page number as it appears in the generated report. It can be the same as the page index or different. Call GetPageNumber( ) from a page only; this method does not apply to frames.

Return value

The page number of a page.


See also

AcBaseFrame::GetPageIndex method


AcBaseFrame::MakeContents method

Example

Called by Start( ) to instantiate the contents of the frame or page.

Syntax

Sub MakeContents( )

Description

The MakeContents( ) method builds the contents as specified in the structure pane of the Design Editor. You can override MakeContents( ) to perform some extra processing. For example, you can conditionally add or delete controls if you want to change the default process for building controls. If you want to include the default process along with your own process, be sure to call the superclass version of MakeContents( ). Otherwise, you do not need to call the superclass.


Example

The following example shows how you override MakeContents( ) to remove a control from one frame's content list and add the control to another frame's content list. In the example, OuterFrame contains InnerFrame, and MakeContents( ) removes CustomerNameControl from InnerFrame and adds it to OuterFrame.

' Override OuterFrame's GetContentIterator( ) to iterate over
' the contents in OuterFrame

Function GetContentIterator( ) As AcIterator

Dim contents As AcOrderedCollection

Set contents = GetContents( )

If contents Is Nothing Then

Set contents = New AcSingleList

End If

Set GetContentIterator = contents.NewIterator( )

End Function

' Override OuterFrame's MakeContents( ) to remove a control from
' InnerFrame and add it to OuterFrame

Sub MakeContents( )

Super::MakeContents( )

Dim iter As AcIterator

Dim content As AcReportComponent

' Find InnerFrame

Set iter = GetContentIterator( )

Do While iter.HasMore( )

Set content = iter.GetNext( )

If GetClassName(content) = "NewReportApp::InnerFrame" Then

Dim control As AcControl

Dim fContent As AcFrame

Set fContent = content

' Find the control to remove

Set control = fContent.FindContentByClass
("NewReportApp::InnerFrame::CustomerNameControl")

' Remove the control from InnerFrame

fContent.GetContents().Remove(control)

' Add the control to OuterFrame

Set control.Container = Nothing

control.Position.X = 10000

control.Position.Y = 1000

AddContent(control)

End If

Loop

End Sub


AcBaseFrame::RebindToFlow method

Called by the framework for controls that appear within a subpage.

Syntax

Sub RebindToFlow( flow As AcFlow )

flow

The flow that contains the component.

Description

The framework calls RebindToFlow( ) for controls that appear within a subpage if that subpage has its BalanceFlows property set to True. RebindToFlow( ) informs the control that the flow that contains that control has changed as a result of the rebalancing. If you override this method, you must call the superclass implementation.


AcBaseFrame::Start method

See also

Instantiates all the contents of the frame or page.

Syntax

Sub Start( )

Description

The Start( ) method instantiates all the contents of the frame or page by calling MakeContents( ) on each of the frame's contents.

Start( ) is part of the framework's core protocol. Override Start( ) in the AcFrame class if you want to perform some special processing in the frame that is unrelated to its contents. For example, you might want to conditionally change the background color of the frame.

If you want to manipulate the contents of a frame, for example, add or remove controls, override the frame's MakeContents( ) method.


See also

AcBaseFrame::MakeContents method


Class AcBasePage

An abstract base class that defines the logic for instantiating the contents of pages.

Description

AcBasePage is the abstract base class for the two types of page components used in a report design: AcPage and AcSubPage.

AcPage describes the physical attributes, such as size and page numbering, of the pages in a report. Subpages exist in flows, and are used to add a different set of flows within a page, for example, to combine a one-column flow with a two-column flow on a single page.

Subclassing AcBasePage

Because AcBasePage is an abstract base class, you generally do not derive directly from it.

Properties

Property	Type	Description
BalanceFlows	Boolean	Ensure that the contents of the flows on the subpage are even.


Class AcCollection

See also   Methods

The abstract base class for the Actuate collection classes.

Description

Collections hold objects of any type. The methods on collections pass references to these objects as a special type called AnyClass. You must assign the object reference to a handle of your derived class in order to access the methods on your object.

You must take care to store the correct kind of objects in each of your collections. For example, if you create a collection of controls, you can also store a data adapter in that collection. However, if your code expects all the objects in the collection to be controls, a run time error occurs when you try to assign the data adapter to an object reference variable for a control.

Subclassing AcCollection

Because AcCollection is an abstract base class, you generally do not derive directly from it.

Methods

Method	Type	Description
NewIterator( )	AcIterator	Creates an iterator for the collection.
RemoveAll( )	N/A	Removes all contents from the collection.
Remove( )	N/A	Removes a specified item from the collection.
IsEmpty( )	Boolean	Reports whether the collection is empty or not.
GetCount( )	Integer	Returns the number of objects in the collection.


See also

Class AcIterator

Class AcOrderedCollection


Methods for class AcCollection

AcCollection::NewIterator method

AcCollection::RemoveAll method

AcCollection::Remove method

AcCollection::IsEmpty method

AcCollection::GetCount method


AcCollection::NewIterator method

Example   See also

Creates an iterator for the collection.

Syntax

Function NewIterator( ) As AcIterator

Description

Use NewIterator( ) to create an iterator over a collection. The iterator lets you access each item in the collection. If the collection is ordered, the iterator accesses each item in the order you established previously.

Return value

A reference to the iterator.


Example

In the following example, a frame's GetContentIterator( ) method is overridden to create an iterator to access the frame's contents. NewIterator( ) is called to instantiate the iterator.

Function GetContentIterator( ) As AcIterator

Dim contents As AcOrderedCollection

Set contents = GetContents( )

If contents Is Nothing Then

Set contents = New AcSingleList

End If

Set GetContentIterator = contents.NewIterator( )

End Function


See also

Class AcIterator


AcCollection::RemoveAll method

See also

Removes all contents from the collection.

Syntax

Sub RemoveAll( )

Description

Use RemoveAll( ) to delete all the contents from a collection. To remove a single object from a collection, use Remove( ).

Actuate automatically deletes objects if they are transient and their reference count goes to zero.


See also

AcCollection::Remove method


AcCollection::Remove method

Example   See also

Removes a specified item from the collection.

Syntax

Sub Remove( item As AnyClass )

item

The object in the collection to delete.

Description

Use Remove( ) to delete an object from the collection. If you specify an object that is not in the collection, Remove( ) does nothing. To remove all objects in a collection, use RemoveAll( ).

Actuate automatically deletes objects if they are transient and their reference count goes to zero.


Example

The following example shows:

1	Overriding a page's GetContentIterator( ) method to create an iterator to access controls on the page.

2	Overriding the page's Build( ) method to locate a specific control and delete it with Remove( ).

Function GetContentIterator( ) As AcIterator

Dim contents As AcOrderedCollection

Set contents = GetContents( )

If contents Is Nothing Then

Set contents = New AcSingleList

End If

Set GetContentIterator = contents.NewIterator( )

End Function

Sub Build( )

    Super::Build( )

    Dim iter as AcIterator

Dim content as AcReportComponent

Set iter = GetContentIterator( )

Do while iter.HasMore( )

Set content = iter.GetNext( )

Dim control As AcControl

Set control = FindContentByClass( "EllipseControl" )

GetContents( ).Remove( control )

Loop

End Sub


See also

AcCollection::RemoveAll method


AcCollection::IsEmpty method

See also

Reports whether the collection is empty or not.

Syntax

Function IsEmpty( ) As Boolean

Description

Use IsEmpty( ) to determine if a collection contains objects. To determine the number of objects in a collection, use GetCount( ).

Return value

True if the collection contains no objects.

False if the collection contains at least one object.


See also

AcCollection::GetCount method


AcCollection::GetCount method

See also

Returns the number of objects in the collection.

Syntax

Function GetCount( ) As Integer

Description

Use GetCount( ) to determine the number of objects in a collection. To determine if a collection contains objects, use IsEmpty( ).

Return value

The number of objects in the collection.


See also

AcCollection::IsEmpty method


Class AcComponent

See also   Methods

The principal base class for the Actuate foundation classes.

Description

AcComponent serves as the root for the AFC framework. All classes that appear in the structure pane of the Design Editor are derived from AcComponent. AcComponent defines the mechanism for creating objects within container objects.

Within the AFC framework, most classes are derived from AcComponent. However, several classes are not derived from AcComponent because they are not part of the report structure, rather they are classes that provide services to the report. Such classes include AcDBCursor, AcDBStatement, and AcIterator.

Subclassing AcComponent

Because AcComponent is the foundation for the AFC framework, you generally do not derive directly from AcComponent.

Methods

Method	Type	Description
Delete( )	N/A	Destructor.
GetContentName( )	String	Returns the name of the component in a specified slot.
IsPersistent( )	Boolean	Returns whether the component is persistent (True) or transient (False).
New( )	N/A	Constructor.
NewComponent( )	AcComponent	Specifies the logic for creating transient objects.
NewPersistent Component( )	AcComponent	Specifies the logic for creating persistent objects.


See also

Class AcReportComponent

Class AcReport

Class AcConnection


Methods for class AcComponent

AcComponent::Delete method

AcComponent::GetContentName method

AcComponent::IsPersistent method

AcComponent::New method

AcComponent::NewComponent method

AcComponent::NewPersistentComponent method


AcComponent::Delete method

See also

The Delete( ) method is the Basic destructor. In derived classes, Delete( ) is called by Actuate Basic when deleting transient objects that are no longer needed.

Syntax

Sub Delete( )

Description

Actuate Basic calls Delete( ) to destroy transient objects when they have completed their tasks. The destructor for the most derived class is called first, followed by all the destructors in the ancestor classes in order of their position in the class hierarchy.

In derived classes, you can override Delete( ) to perform cleanup tasks such as closing files. To do this, call Super::Delete( ) as the last line of your method.


See also

AcComponent::New method


AcComponent::GetContentName method

Returns the name of the component in a specified slot.

Syntax

Function GetContentName( rel As String ) As String

Function GetContentName( rel As String, index As Integer ) As String

rel

The name of a structure relationship as it appears in the structure pane of the Design Editor or in this reference manual.

index

If the structure relationship is a list, use the second form of this method and specify the list location (starting with 1) of the component you want to query.

Description

Use GetContentName( ) to find what component (if any) exists in a particular slot for a component. The function returns an empty string if either the relationship name is invalid, or if nothing exists in that slot. The index lets you query list relationships such as Content for a frame, that can have multiple contents. You can also specify an index location that you want to query.

You can determine the number of items in the list by writing a loop to query the components starting at index 1. The method will return an empty string which means that the current index is one past the end of the list.

You use the first form (without the index) for single relationships, such as the Before slot of a report section. The form without the index is equivalent to calling the second form with an index of 1. (That is, a single relationship looks like a list with 0 or 1 elements.)

Return value

The name of the component.


AcComponent::IsPersistent method

Returns whether the component is persistent or transient.

Syntax

Function IsPersistent( ) As Boolean

Description

Use IsPersistent( ) to determine whether the component is persistent (stored in the .ROI file) or transient (deleted from memory when the report is finished).

Return value

True if the component is persistent.

False if the component is transient.


AcComponent::New method

Constructor. In derived classes, called by Actuate Basic after the object has been instantiated.

Syntax

Sub New( )

Description

New( ) initializes all the properties set through the Component Editor.

In derived classes, you typically override New( ) to initialize user-defined variables. If you override New( ), you must call Super::New( ) as the first line of your method so that SetProperties( ) can initialize property values.


AcComponent::NewComponent method

See also

Specifies the logic for creating transient objects.

Syntax

Function NewComponent( rel As String ) As AcComponent

Function NewComponent( rel As String, index As Integer ) As AcComponent

rel

The name of the relationship between the objects in the structure pane. The name of the relationship is shown in the Properties list. For example, if a report uses a data stream, the generated code is

NewComponent( "DataStream" )

index

The content's position in the structure pane if the container object creates and holds multiple objects.

Description

Derived classes call NewComponent( ) to create transient objects as they are represented in the Design Editor's structure pane. For example, a data source calls NewComponent( ) to create a data row.

Generally, you do not need to override NewComponent( ).

Return value

A reference to the created object in derived classes.

Nothing if the object was not created.


See also

AcComponent::NewPersistentComponent method


AcComponent::NewPersistentComponent method

See also

Specifies the logic for creating persistent objects.

Syntax

Function NewPersistentComponent( rel As String ) As AcComponent

Function NewPersistentComponent( rel As String, index As Integer ) As AcComponent

rel

The name of the relationship between the objects in the structure pane. The name of the relationship is shown in the Properties list. For example, if a group section uses a PageHeader, the generated code is

NewComponent( "PageHeader" )

index

The content's position in the structure pane if the container object creates and contains multiple objects. The following figure illustrates the objects' index values:

Description

Derived classes call NewPersistentComponent( ) to create persistent objects contained within them. For example, a frame calls NewPersistentComponent( ) to create each of its contained controls.

Generally, you do not need to override NewPersistentComponent( ).

Return value

In derived classes, a reference to the created object.

Nothing, if the object is not created.


See also

AcComponent::NewComponent method


Class AcConditionalSection

Methods

A class you use in the report design to instantiate a component in a section, depending on a specified condition.

Description

Use the conditional section to conditionally instantiate one of several components in a section. For example, you can use a conditional section to print a different frame for credit card or cash transactions.

The three general steps to setting up a conditional section are:

1	Specify a Boolean expression in the conditional section's IfExp property.

2	Place a component in the conditional section's Then slot.

3	Place a component in the conditional section's Else slot.

If the IfExp expression evaluates to True, then the conditional section builds the component in its Then slot; otherwise, it builds the component in the Else slot.

At times you may want to create a "case-statement" type of structure, in which your report chooses from one of a group of possible components to generate. The following are the general steps to create this type of structure:

1	Add a sequential section to your report to represent the entire set of possible components.

2	Add conditional sections to the sequential section where each conditional section represents one of these cases.

3	For each conditional section, specify an IfExp value to describe the case.

4	For each conditional section, place a component in the Then slot. This component is instantiated when the IfExp value is True.

With this structure, you can choose your If expressions so that the cases do not overlap, or you can let the cases overlap to instantiate multiple components depending on the condition.

Variables

Variable	Type	Description
KeyValue	Variant	The value of the key column for the group.
Properties

Property	Type	Description
IfExp	Expression	A Boolean expression. If the expression evaluates to True, then the section builds the component in the Then slot; otherwise, it builds the component in the Else slot. If you enter nothing in this slot, then the default value for the condition is True.
Then	AcReportComponent structure reference	Builds this component if IfExp is True.
Else	AcReportComponent structure reference	Builds this component if IfExp is False.
Methods

Method	Type	Description
ConditionIsTrue( )	Boolean	Returns the True/False condition value.
NewElse( )	AcReportComponent	Instantiates the component in the Else slot.
NewThen( )	AcReportComponent	Instantiates the component in the Then slot.


Methods for class AcConditionalSection

AcConditionalSection::ConditionIsTrue method

AcConditionalSection::NewElse method

AcConditionalSection::NewThen method


AcConditionalSection::ConditionIsTrue method

Returns the True/False condition value.

Syntax

Function ConditionIsTrue( row As AcDataRow ) As Boolean

row

The data row, if any, associated with this component. This is the data row passed to the BuildFromRow( ) method of the conditional section. The row returns Nothing if the container component calls Build( ) instead.

Description

The ConditionIsTrue( ) method returns True or False depending on whether the conditional section should instantiate the component in the Then or Else slot accordingly. You can think of the condition as follows.

If ConditionIsTrue( row ) Then

     instantiate Then component

Else

     instantiate Else component

End If

Actuate generates this method for you based on the value you enter in the IfExp property. However, if the expression you want to evaluate is more complex than that property can handle, you can override this method to do the work instead.

Return value

True if the conditional section should instantiate the component in the Then slot.

False if the conditional section should instantiate the component in the Else slot.


AcConditionalSection::NewElse method

Instantiates the component in the Else slot.

Syntax

Function NewElse( ) As AcReportComponent

Description

If the expression entered in the IfExp property evaluates to False, the framework calls NewElse( ) to instantiate the component in the conditional section's Else slot.

Return value

A reference to the component instantiated in the Else slot.


AcConditionalSection::NewThen method

Instantiates the component in the Then slot.

Syntax

Function NewThen( ) As AcReportComponent

Description

If the expression entered in the IfExp property evaluates to True, the framework calls NewThen( ) to instantiate the component in the conditional section's Then slot.

Return value

A reference to the component instantiated in the Then slot.


Class AcConnection

Methods

An abstract base class that defines the core protocol for all connection components.

Description

AcConnection defines the core protocol for connecting to and disconnecting from an input source. Classes derived from AcConnection redefine the methods to perform tasks specific to a database connection.

Actuate provides four connection classes to connect to the following databases: DB2, Informix, Microsoft SQL, ODBC, Oracle, Progress, and Sybase. If you need a connection to any other type of input source, subclass AcConnection to create the connection.

The IsOpen variable contains the current state of the connection. If you derive your own connection classes, keep IsOpen up to date in addition to other work you need to perform.

Variables

Variable	Type	Description
IsOpen	Boolean	True establishes a valid connection.
Methods

Method	Type	Description
Connect( )	Boolean	An empty method for derived classes to override to perform the actual connection to a database.
Disconnect( )	N/A	An empty method for derived classes to override to disconnect from a database.
IsConnected( )	Boolean	Returns whether a database connection is established.
RaiseError( )	N/A	Produces an appropriate error message.


Methods for class AcConnection

AcConnection::Connect method

AcConnection::Disconnect method

AcConnection::IsConnected method

AcConnection::RaiseError method


AcConnection::Connect method

See also

Attempts to connect to the database.

Syntax

Function Connect( ) As Boolean

Description

The Connect( ) method attempts to open the database by establishing a connection. You must have previously set the variables needed to describe the connection.

Derived classes override this method to perform the actual connection to the database.

Return value

True if the connection is established

False if the connection is not.


See also

AcConnection::Disconnect method

AcConnection::IsConnected method


AcConnection::Disconnect method

See also

Disconnects the database.

Syntax

Sub Disconnect( )

Description

Disconnect( ) disconnects from the database if there was a valid connection. Derived classes override this method to perform the actual disconnect.


See also

AcConnection::Connect method

AcConnection::IsConnected method


AcConnection::IsConnected method

See also

Returns whether the connection is established.

Syntax

Function IsConnected( ) As Boolean

Description

Use IsConnected( ) in a control structure to execute tasks depending on whether a connection is opened or closed.

Return value

True if the connection is established.

False if the connection is not established.


See also

AcConnection::Connect method

AcConnection::Disconnect method


AcConnection::RaiseError method

An abstract method that derived classes override to produce error messages.

Syntax

Sub RaiseError( )

Description

Raises a Basic error that describes the database error. Derived classes should override this method to obtain error information from the database connection, then raise the error.

Relational databases usually report error conditions through their connection interface.


Class AcControl

Methods

An abstract base class that defines the core characteristics of all controls.

Description

A control is the primary visual component in a report. You typically place controls in frames to display labels, data, images, drawing elements, and so on. You can also place controls directly on a page, for example, to display the page number or date.

There are two types of controls: constant and data controls. AcControl is the base class for both types of controls.

•	Constant controls, such as labels, lines, and rectangles, are fully defined at design time and need no additional data in the Factory. You can, however, write code to change the attributes of a constant control in the Factory. For example, you can adjust the size of a line based on the dollar amount of a data row field, or change the color of a label to red to show that a particular customer is 60 days past due. To accomplish these tasks, you can override the enclosing frame's OnRow( ) method or the control's BuildFromRow( ) method to add the code.

•	Data controls, such as text, integer, and date/time controls, display values from data rows processed in the Factory. For more information about data controls, see the description of the AcDataControl class.

Like other visual components, controls can respond to viewing events, such as mouse clicks, in the Viewer. You can override a control's viewing methods, inherited from AcVisualComponent, to specify how users interact with controls at view time.

Factory protocol

When you place a control on a report design using the Design Editor, Actuate automatically subclasses the appropriate derived control. The following table describes AcControl's protocol that defines the tasks that all controls perform.

Method	Task
New( )	Initializes the control.
Start( )	Initializes the control.
Build( )	Called if the enclosing frame does not have access to a data row.
BuildFromRow( )	Called if the enclosing frame has access to a data row. Sets the value of the control from the data row.
Finish( )	Completes the control.
Subclassing AcControl

Derive from AcControl only if you want to define a new kind of control. For example, you may want to create a push button control. Typically, you derive a new control from one of the more specialized subclasses of AcControl, such as AcDoubleControl.

Properties

Property	Type	Description
ValueType	AcControl ValueType Function	Determines when the value of the control is built.
Methods

Method	Type	Description
GetControlValue( )	Variant	Returns the value of another control within the same frame.
GetHtmlText( )	String	Converts a control's text to HTML.
GetText( )	String	Returns the text of the control, if any, formatted for display.
GetValue( )	Variant	Returns the value of the control.
PageNo( )	AcPage	Returns the current page number as an integer.
PageNo$( )	String	Returns the formatted current page number as a string.


Methods for class AcControl

AcControl::GetControlValue method

AcControl::GetHtmlText method

AcControl::GetText method

AcControl::GetValue method

AcControl::PageNo method

AcControl::PageNo$ method


AcControl::GetControlValue method

Example   See also

Returns the value of another control within the same frame.

Syntax

Function GetControlValue( controlName As String ) As Variant

controlName

The name of the control for which you want the value. Specify the control with its fully qualified name (for example, OrdersReport::ItemFrame::PriceControl) or just the control's name (for example, PriceControl).

Description

Use GetControlValue( ) to get the value of another control within the same frame. If, for example, you want to change the value or property of one control depending on the value of another control, you can call GetControlValue( ) from the first control to get the value of the second control.

GetControlValue( ) first finds the control, then calls that control's GetValue( ) method to obtain the value. If you call GetControlValue( ) to get the value of a control before its value is set, GetControlValue( ) returns Null.

If you use GetControlValue( ) in a custom implementation of SetValue( ), you must be aware of the order in which controls are built. Generally, the controls of a frame are built in the same order that they appear in the structure pane.

Return value

The value of the specified control.

Null if the specified control's value has not been set.


Example

In the following example, a label control's BuildFromRow( ) method is overridden so that the label's font color is set to red when the value of an integer control, DaysOverdue, is greater than 30. GetControlValue( ) returns the value of the DaysOverdue integer control. Both the label and integer controls are in the same frame.

Function BuildFromRow( row As AcDataRow ) As AcBuildStatus

    BuildFromRow = Super::BuildFromRow( row )

    If GetControlValue("DaysOverdue") > 30 Then

Font.Color = Red

End If

End Function


See also

AcBaseFrame::GetControlValue method


AcControl::GetHtmlText method

See also

Format's a control's text for display in HTML.

Syntax

Function GetHtmlText( ) As String

Description

GetHtmlText( ) uses the GetText( ) method to get the text for a control, then converts the text to HTML using the Actuate Basic function ConvertToHtml( ). Override this method to have control of HTML text formatting in your HTML reports.


See also

ConvertToHtml Actuate Basic function


AcControl::GetText method

See also

Formats a control's value for display.

Syntax

Function GetText( ) As String

Description

The framework calls GetText( ) to format the data value of data controls and the text value of label controls. In derived classes, such as AcTextControl or AcIntegerControl, GetText( ) formats a control's data value by calling the Actuate Basic Format$ function and using the format pattern you specified in the control's Format property.

You can override a control's GetText( ) method to perform additional formatting, for example, to translate a numeric value into a string of words for printing on a check.

Return value

The text to display in the control.


See also

AcDataControl::Format method


AcControl::GetValue method

See also

Returns the value of the control.

Syntax

Function GetValue( ) As Variant

Description

If the control is a data control, GetValue( ) returns the value in the DataValue property. If the control is not a data control, this method returns Null.

Return value

The value of the control.


See also

AcDataRow::GetValue method


AcControl::PageNo method

See also

Returns the page index of the control.

Syntax

Function PageNo( ) As Integer

Description

PageNo( ) returns the position of the page in the report, starting from one. For example, to show the page number in a control, set the value of the control to PageNo( ).

This method can be used for a control directly on a page, or for a control in a frame in a PageHeader or PageFooter slot. It is not applicable to other frames because the page is not known when the value of the control is set.

PageNo( ) raises an error if it is called before the frame holding this control is added to a page.

Return value

An integer indicating the page index of this control.


See also

AcControl::PageNo$ method

AcVisualComponent::GetPage method


AcControl::PageNo$ method

See also

Returns the formatted page number of the control.

Syntax

Function PageNo$( ) As String

Description

The PageNo$ method returns the formatted page number of the control as a string. For example, to show the formatted page number such as vi, 107, or 12-5 in a control, set the value of the control to PageNo$.

This method can be used for a control directly on a page, or for a control in a frame in a PageHeader or PageFooter slot. It is not applicable to other frames because the page is not known when the value of the control is set.

PageNo$( ) will raise an error if it is called before the frame holding this control is added to a page.

Return value

A string containing the formatted page number of this control.


See also

AcControl::PageNo method

AcVisualComponent::GetPage method


Class AcCurrencyControl

A class you use in the report design to display a currency number.

Description

Use the currency control to store and display a currency number. While you can use the double control to display monetary values, the currency control provides a greater level of precision, that is, the currency type is not subject to rounding errors.

AcCurrencyControl defines a DateValue variable to store the currency value. The framework generates SetValue( ) to set the value in DataValue. SetValue( ) uses the value expression you assign to the ValueExp property to generate the value. Override SetValue( ) if you want to take control of setting the control's data value.

Variables

Variable	Type	Description
DataValue	Currency	Holds the currency value. The default is null.


Class AcDataAdapter

See also   Methods

An abstract base class that defines the logic of classes that form a data stream. The data stream collects, processes, and delivers data to the report. The parts of a data stream are called data adapters.

Description

AcDataAdapter is the abstract base class for the two types of data adapter base classes: AcDataSource and AcDataFilter.

Data sources collect data from an input source, such as a database or a spreadsheet. Data filters process the collected data. Both work together to produce and deliver formatted data, called data rows, to the report. You can limit the number of data rows a data adapter retrieves by using the FetchLimit property. This feature is useful for testing and debugging report designs, especially those that generate large numbers of pages.

AcDataAdapter defines the core logic for how data adapters work with connections and data rows. It also defines the basic algorithms for random access to data.

Factory protocol

The following table describes AcDataAdapter's protocol that defines the tasks that all data adapters perform.

Method	Task
New( )	Initializes the data adapter.
Start( )	Opens the data adapter. For a data source, this method opens the input source from which data is to be read. For a data filter, this method opens the input adapter(s). An input adapter is the data adapter that supplies data rows to the data filter.
Fetch( )	Reads one row from the data adapter.
Finish( )	Closes the data adapter. For a data source, this method closes the input source. For a data filter, this method closes the input adapter(s).
Subclassing AcDataAdapter

You typically derive from one of AcDataAdapter's more specialized subclasses.

Variables

Variable	Type	Description
FetchLimit	Integer	The number of data rows the data adapter retrieves.
IsOpen	Boolean	True when the data adapter is open. The IsOpen variable is set to True in Start( ) and is set to False in Finish( ). Use IsStarted( ) to obtain the value of this variable.
Position	Integer	The current input position. Position is set to 1 in Start( ) and is incremented on each call to AddRow( ). You must maintain Position in your other overridden methods. Use GetPosition( ) to obtain the value of this variable.
Properties

Property	Type	Description
Connection	AcConnection  Structure Reference	Identifies the connection to use for the data adapter.
DataRow	AcDataRow Structure Reference	Identifies the data row to use with the data adapter.
FetchLimit	Integer	The number of data rows the data adapter retrieves. The capability to limit the number of data rows is useful for testing and debugging report designs when you need a small data sample.
Methods

Method	Type	Description
AddRow( )	N/A	Adds a row to the data adapter.
AddSortKey( )	N/A	Adds a dynamic sort key column.
CanSeek( )	Boolean	Returns True if the data adapter supports random access.
CanSortDynamically( )	Boolean	Determines if the data adapter supports dynamic ordering.
CloseConnection( )	N/A	Closes the connection.
Fetch( )	AcDataRow	Reads the row (if any) at the position identified by GetPosition( ).
Finish( )	N/A	Closes a data adapter.
FlushBuffer( )	N/A	Flushes all buffered rows.
FlushBufferTo( )	N/A	Flushes all buffered rows up to the row specified.
GetConnection( )	AcConnection	Returns the connection associated with the data adapter.
GetPosition( )	Integer	Returns the position of the next row that will be fetched.
IsStarted( )	Boolean	Returns True if the data adapter is open.
NewConnection( )	AcConnection	Instantiates the connection specified in the data adapter's Connection slot.
NewDataRow( )	AcDataRow	Instantiates a data row based on the DataRow property.
OpenConnection( )	Boolean	Opens a connection.
Rewind( )	N/A	Moves the fetch position to the beginning of the input set.
SeekBy( )	N/A	Moves the fetch position by a given amount relative to the current position.
SeekTo( )	N/A	Moves the fetch position to a given location.
SeekToEnd( )	N/A	Moves the fetch position to one past the end of the input set.
SetConnection( )	N/A	Suggests a connection to be used unless the data adapter already has its own connection.
Start( )	Boolean	Opens the data adapter.


See also

Class AcDataRow

Class AcDataSource

Class AcMultipleInputFilter

Class AcSingleInputFilter


Methods for class AcDataAdapter

AcDataAdapter::AddRow method

AcDataAdapter::AddSortKey method

AcDataAdapter::CanSeek method

AcDataAdapter::CanSortDynamically method

AcDataAdapter::CloseConnection method

AcDataAdapter::Fetch method

AcDataAdapter::Finish method

AcDataAdapter::FlushBuffer method

AcDataAdapter::FlushBufferTo method

AcDataAdapter::GetConnection method

AcDataAdapter::GetPosition method

AcDataAdapter::IsStarted method

AcDataAdapter::NewConnection method

AcDataAdapter::NewDataRow method

AcDataAdapter::OpenConnection method

AcDataAdapter::Rewind method

AcDataAdapter::SeekBy method

AcDataAdapter::SeekTo method

AcDataAdapter::SeekToEnd method

AcDataAdapter::SetConnection method

AcDataAdapter::Start method


AcDataAdapter::AddRow method

See also

Adds a row to the data adapter.

Syntax

Sub AddRow( row As AcDataRow )

row

The newly created data row.

Description

If you override the Fetch( ) method, call AddRow( ) after you instantiate the data row and set its variables.

AddRow( ) does the following three things:

1	Sets the row's RowNumber variable to the current input position.

2	Advances the input position.

3	Calls the OnRead( ) method for the data row so the row can compute its computed column values.


See also

AcDataAdapter::Fetch method

AcDataRow::OnRead method


AcDataAdapter::AddSortKey method

See also

Adds a dynamic sort key column.

Syntax

Sub AddSortKey( keyName As String, sortSense As AcSortSense )

keyName

The name of one of the columns in the SELECT clause.

sortSense

The direction of the sort. Specify either SortAscending or SortDescending

Description

Group sections provide the ability to automatically update the ORDER BY clause of the SELECT statement for an SQL query source to match the sequence needed by your report. The group sections inform the data source of the preferred sort order by calling AddSortKey( ) and passing the group section's Key property value.

If you write code that uses a data source, your custom code can call AddSortKey( ) to customize the sort order of the data. If you create a custom data adapter, you can optionally override this method to support custom run-time sorting.

Unless a subclass specifically overrides this method, the base AcDataAdapter class assumes that dynamic sorting is not supported, and if the application calls this method, it will raise a run-time error.


See also

AcDataAdapter::CanSortDynamically method


AcDataAdapter::CanSeek method

Determines whether the data adapter supports random access to data.

Syntax

Function CanSeek( ) As Boolean

Description

CanSeek( ) returns False by default. In derived classes, you can override this method to return True if you want support for random access.

Return value

True if the data adapter supports random access.

False if the data adapter does not support random access.


AcDataAdapter::CanSortDynamically method

See also

Determines if the data adapter supports dynamic ordering.

Syntax

Function CanSortDynamically( ) As Boolean

Description

AcDataAdapter assumes that the adapter does not support dynamic sorting, so by default, CanSortDynamically( ) returns False. If your custom data adapter supports sorting, you can override this method to return True, and then override AddSortKey( ) to accept the sort columns.

You should call CanSortDynamically( ) to ensure that a data adapter supports custom sorting before calling AddSortKey( ).

Return value

True if the data adapter supports dynamic ordering.

False if the data adapter does not support dynamic ordering.


See also

AcDataAdapter::AddSortKey method


AcDataAdapter::CloseConnection method

See also

Closes the connection returned by NewConnection( ).

Syntax

Sub CloseConnection( connection As AcConnection)

connection

The connection to close.

Description

If NewConnection( ) returns a local connection, then the data adapter calls CloseConnection( ) to close the connection. For information about overriding this method, see OpenConnection( ).


See also

AcDataAdapter::GetConnection method

AcDataAdapter::NewConnection method

AcDataAdapter::OpenConnection method

AcDataAdapter::SetConnection method


AcDataAdapter::Fetch method

Example

Reads the row (if any) at the position identified by GetPosition( ).

Syntax

Function Fetch( ) As AcDataRow

Description

Fetch( ) reads one row from the data adapter. Specifically, Fetch( ) reads the row (if any) at the position identified by GetPosition( ). Fetch( ) then advances the position by one, unless the current position was past the end of the input set; in which case, Fetch( ) returns Nothing.

If you create a custom data source or filter, you must override this method to fetch a row. You must handle repeated calls to Fetch( ), even after Fetch( ) has reached the end of the input set. Also, your override should call AddRow( ) each time it instantiates a new row.

If you write a custom Fetch( ) method for a data filter, and your Fetch( ) method simply passes along rows created by an input adapter, then you should not call AddRow( ) because it was already called by the input adapter. Instead, increment Position directly.

When you override a data adapter's Fetch( ) method, the FetchLimit property value has no effect. You need to write code if you want to limit the number of data rows to retrieve.


Example

The following example shows you how to roll up the projected and actual cost figures for each month, and graph the accumulated results, when the data is not normalized. To view the code used in this example in a fuller context, open examples\BUDGRPT.ROD, highlight the data filter, SumGraphDataFilter, and examine its Fetch( ) method.

To graph this data, the report must receive the data as one amount per row. For example, one row for January Budget, one row for January Actual, and so on. Use a data filter to normalize the data returned from the query.

The following code in the Fetch( ) method of the filter receives a data row from the data source SqlQuerySource, which contains the database query.

Each time Fetch( ) is called, the data filter splits off another amount field and returns it to the report. The dollars are accumulated each month. For example, the budget amount for March shows the sum of January, February, and March budgets.

Function Fetch( ) As AcDataRow

Dim aFilterDataRow As FilterDataRow

' Get the row returned from the SQL Query

If queryDataRow is Nothing Then

Set queryDataRow = InputAdapter.Fetch()

If queryDataRow Is Nothing Then

Exit Function

End If

dataPointCount = 0

actualTotal = 0.0

planTotal = 0.0

End If

' Run through each of the twelve monthly fields on the query data row and

' return one row for each month/amount combination to the report

Set aFilterDataRow = New FilterDataRow

aFilterDataRow.month = ( dataPointCount \ 2 ) + 1

aFilterDataRow.amountType = dataPointCount MOD 2

'Type of 0 = actual, 1 = plan

dataPointCount = dataPointCount + 1

If dataPointCount = 25 Then

Exit Function

End If

Select Case dataPointCount

Case 1

aFilterDataRow.amountToGraph = queryDataRow.aJanDollars

Case 2

aFilterDataRow.amountToGraph = queryDataRow.bJanDollars

Case 3

aFilterDataRow.amountToGraph = queryDataRow.aFebDollars

Case 4

aFilterDataRow.amountToGraph = queryDataRow.bFebDollars

Case 5

aFilterDataRow.amountToGraph = queryDataRow.aMarDollars

Case 6

aFilterDataRow.amountToGraph = queryDataRow.bMarDollars

Case 7

aFilterDataRow.amountToGraph = queryDataRow.aAprDollars

Case 8

aFilterDataRow.amountToGraph = queryDataRow.bAprDollars

Case 9

aFilterDataRow.amountToGraph = queryDataRow.aMayDollars

Case 10

aFilterDataRow.amountToGraph = queryDataRow.bMayDollars

Case 11

aFilterDataRow.amountToGraph = queryDataRow.aJunDollars

Case 12

aFilterDataRow.amountToGraph = queryDataRow.bJunDollars

Case 13

aFilterDataRow.amountToGraph = queryDataRow.aJulDollars

Case 14

aFilterDataRow.amountToGraph = queryDataRow.bJulDollars

Case 15

aFilterDataRow.amountToGraph = queryDataRow.aAugDollars

Case 16

aFilterDataRow.amountToGraph = queryDataRow.bAugDollars

Case 17

aFilterDataRow.amountToGraph = queryDataRow.aSepDollars

Case 18

aFilterDataRow.amountToGraph = queryDataRow.bSepDollars

Case 19

aFilterDataRow.amountToGraph = queryDataRow.aOctDollars

Case 20

aFilterDataRow.amountToGraph = queryDataRow.bOctDollars

Case 21

aFilterDataRow.amountToGraph = queryDataRow.aNovDollars

Case 22

aFilterDataRow.amountToGraph = queryDataRow.bNovDollars

Case 23

aFilterDataRow.amountToGraph = queryDataRow.aDecDollars

Case 24

aFilterDataRow.amountToGraph = queryDataRow.bDecDollars

End Select

If aFilterDataRow.amountType = 0 Then

aFilterDataRow.amountToGraph = aFilterDataRow.amountToGraph + actualTotal

actualTotal = aFilterDataRow.amountToGraph

Else

aFilterDataRow.amountToGraph = aFilterDataRow.amountToGraph + planTotal

planTotal = aFilterDataRow.amountToGraph

End If

Set Fetch = aFilterDataRow

End Function

Return value

A reference to the data row fetched.

Nothing if the current position was past the end of the input set.


AcDataAdapter::Finish method

See also

Closes the data adapter.

Syntax

Sub Finish( )

Description

Finish( ) closes the data adapter. If the data adapter is a data source, Finish( ) closes the input source (which may be a query, a file, and so on). If the data adapter is a filter, Finish( ) closes each of the input adapters. An input adapter is the data adapter that supplies data rows to the data filter.

If the connection was created with NewConnection( ), Finish( ) calls CloseConnection( ) to close the connection.

In derived classes, you can override Finish( ) to do additional work when the Factory finishes processing the data adapter. Call Super::Finish after your code.

See AcBaseFrame::Finish method for an example showing how to use the Finish( ) method.


See also

AcDataAdapter::Start method

AcBaseFrame::Finish method


AcDataAdapter::FlushBuffer method

See also

If the data adapter uses internal buffering to enable random access, this method flushes all the buffered rows.

Syntax

Sub FlushBuffer( )

Description

Call FlushBuffer( ) to clear the buffer when you no longer need the rows and need to reclaim memory. FlushBuffer( ) calls FlushBufferTo( ) to actually clear the buffer. FlushBuffer( ) does nothing if the data source does not use buffering.

After the buffer is flushed, the read position will be set to the first row past those that were in the buffer.

Derived classes that support buffering should override this method.


See also

AcDataAdapter::FlushBufferTo method

AcMemoryBuffer::FlushBuffer method

AcMemoryBuffer::FlushBufferTo method


AcDataAdapter::FlushBufferTo method

See also

Flushes all buffered rows.

Syntax

Sub FlushBufferTo( posn As Integer )

posn

The data row to flush to.

Description

Call FlushBufferTo( ) to clear all rows, up to and including a specified row. If the data adapter supports buffering and the read position is less than posn, the current read position is set to posn + 1.


See also

AcDataAdapter::FlushBuffer method

AcMemoryBuffer::FlushBuffer method

AcMemoryBuffer::FlushBufferTo method


AcDataAdapter::GetConnection method

See also

Returns a connection.

Syntax

Function GetConnection( ) As AcConnection

Description

Call GetConnection( ) to get the connection associated with the data adapter. You might need to get a connection if you want to customize the process of selecting and instantiating a connection. For example, you might call GetConnection( ) to return the connection, which you then pass as an argument to SetConnection( ).

Return value

A reference to the connection associated with the data adapter.


See also

AcDataAdapter::CloseConnection method

AcDataAdapter::NewConnection method

AcDataAdapter::OpenConnection method

AcDataAdapter::SetConnection method


AcDataAdapter::GetPosition method

Returns the position of the next row that will be fetched.

Syntax

Function GetPosition( ) As Integer

Description

GetPosition( ) returns the position (starting with 1) of the next row that will be fetched. The number of rows fetched to date from a sequential source is one less than GetPosition( ).

Return value

The current row number or 1 when the data adapter is first opened.


AcDataAdapter::IsStarted method

Returns True if the adapter is open. False otherwise.

Syntax

Function IsStarted( ) As Boolean

Description

Returns True if your data adapter has been opened by a call to Start( ). Returns False if the data adapter has never been started, or if it was closed by a call to Finish( ).

Return value

The value of the IsOpen variable.


AcDataAdapter::NewConnection method

See also

Instantiates a new connection.

Syntax

Function NewConnection( ) As AcConnection

Description

NewConnection( ) instantiates the connection class, if any, that you placed in the Connection slot of the data adapter in the structure pane. You can override this method to customize the process for selecting a connection. For example, if your report needs a different connection depending on the data adapter being used, you would override NewConnection( ) to write the conditional logic.

Return value

The new connection.


See also

AcDataAdapter::CloseConnection method

AcDataAdapter::GetConnection method

AcDataAdapter::OpenConnection method

AcDataAdapter::SetConnection method


AcDataAdapter::NewDataRow method

Instantiates the data row class that appears in the DataRow slot for this adapter.

Syntax

Function NewDataRow( ) As AcDataRow

Description

NewDataRow( ) instantiates the data row, if any, that you placed in the DataRow slot of the data adapter in the structure pane. You can override this method to customize the data row to instantiate.

Fetch( ) calls NewDataRow( ) each time it reads a new data row. If you create a custom data source and override Fetch( ) to specify how the data source retrieves data rows, call NewDataRow( ) to instantiate the data row. For an example of creating a custom data source, see Chapter 9, "Customization examples," in Programming with Actuate.

Return value

The new data row.


AcDataAdapter::OpenConnection method

Example   See also

Opens the connection returned by NewConnection( ).

Syntax

Function OpenConnection( connection As AcConnection ) As Boolean

connection

The connection to open.

Description

If NewConnection( ) returns a local connection, the data adapter calls OpenConnection( ) to open the connection. You can override this method if you need to customize the connection before opening it.

For example, suppose you have five data sources in a report. The first and third data sources use an Oracle connection, and the others use an ODBC connection. You could place the ODBC connection in the common section, then create a static variable to hold the Oracle connection. In the data adapters that work with the Oracle connection, override NewConnection( ) to get the shared connection, then override OpenConnection( ) and CloseConnection( ) to do nothing (assuming that code elsewhere will handle opening and closing the Oracle connection).

Return value

True if the connection was opened.

False if the connection was not opened.


Example

The data adapter may choose to set the database or user name based on a parameter. If so, your overridden method should call any superclass method and return the value of that method as follows:

Function OpenConnection( connection As AcConnection ) As Boolean

Dim conn As AcODBCConnection

Set conn.DataSource = "testDB"

OpenConnection = Super::OpenConnection( connection)

End Function

Or, you can override this method, along with NewConnection( ) and CloseConnection( ), to implement a custom scheme for sharing connections.


See also

AcDataAdapter::CloseConnection method

AcDataAdapter::GetConnection method

AcDataAdapter::NewConnection method

AcDataAdapter::SetConnection method


AcDataAdapter::Rewind method

Moves the fetch position to position one.

Syntax

Sub Rewind( )

Description

Moves the current input position to the beginning of the input set. This method is equivalent to:

SeekTo( 1 )


AcDataAdapter::SeekBy method

Moves the fetch position by a given amount, relative to the current position.

Syntax

Sub SeekBy( offset As Integer )

offset

The number of rows, relative to the current position, to move.

Description

Moves the current input position by a relative amount. If you specify an offset of 0, then the position does not move. Negative offsets move the position toward the beginning of the input set, positive offsets move the position toward the end of the input set. This method works just like SeekTo( ). In fact, it is equivalent to the following:

SeekTo( GetPosition( ) + offset )

Derived classes need not override this method. They should override SeekTo( ) instead.


AcDataAdapter::SeekTo method

Moves the fetch position to a given location.

Syntax

Sub SeekTo( posn As Integer )

posn

The position from which to read on the next Fetch( ).

Description

Moves the current input position to the position specified. Position is relative to the beginning of the input set; the first row is position one. If you specify a position less than one, then the data adapter will use position one instead. Similarly, if you seek to a position past the end of the input set, the position will be set to one past the end of the file.

After a call to SeekTo( ), the next call to GetPosition( ) will return the position that you specified, subject to the above constraints. Similarly, the next call to Fetch( ) will return the row (if any) at the position you specify.

This method is available only in data adapters that support random access. If the adapter provides only sequential access, then this method will raise a run-time error.

Derived classes that support random access must override this method.


AcDataAdapter::SeekToEnd method

Moves the fetch position to one past the end of the input set.

Syntax

Sub SeekToEnd( )

Description

Reads rows from the current position to the end of the input set. This method is equivalent to calling Fetch( ) in a loop until Fetch( ) returns Nothing.

After a call to SeekToEnd( ), GetPosition( ) returns one greater than the number of rows in the input set.

Derived classes need not override this method.


AcDataAdapter::SetConnection method

See also

Sets a connection for the data adapter.

Syntax

Sub SetConnection( theConnection As AcConnection )

Description

Call SetConnection( ) to specify a connection to use. The connection must already be open, and you must call SetConnection( ) before calling Start( ). Any connection returned by NewConnection( ), however, has precedence.


See also

AcDataAdapter::CloseConnection method

AcDataAdapter::GetConnection method

AcDataAdapter::NewConnection method

AcDataAdapter::OpenConnection method


AcDataAdapter::Start method

See also

Opens the data adapter.

Syntax

Function Start( ) As Boolean

Description

For a data source, Start( ) opens the input source from which data is to be read. For a data filter, Start( ) opens the input adapter(s), the data adapter that supplies data rows to the data filter.

Start( ) also calls NewConnection( ) to instantiate the connection. If NewConnection( ) returns a connection, then Start( ) calls OpenConnection( ) to open the connection.

You can override Start( ) to add additional startup code for your class. You should, however, call the superclass method first, then continue with your own initialization only if the superclass method returns True.

Function Start( ) As Boolean

Start = Super::Start( )

If Not Start Then

Exit Function

End If

' Custom startup code

End Function

Return value

True if the data adapter is opened

False otherwise.


See also

AcDataAdapter::Finish method


Class AcDatabaseSource

See also   Methods

An abstract base class for data sources that retrieve data from databases.

Description

AcDatabaseSource is an abstract base class that provides the standard logic for retrieving rows from a relational database cursor. It defines the methods for binding parameters to the database statement, opening the cursor, binding the data row to the cursor, retrieving rows from the cursor, and closing the cursor.

Subclassing AcDatabaseSource

Derive directly from AcDatabaseSource to create a data source that reads from a stored procedure or from a SELECT statement that you provide. Usually, however, you create a subclass of AcSqlQuerySource and use the Query Editor to build your SELECT statement.

If you derive from AcDatabaseSource, you must do the following:

1	Override the Start( ) method to create a SQL statement.

2	Override BindDataRow( ) method to bind your data row to the cursor.

Methods

Method	Type	Description
BindDataRow( )	N/A	Binds the data row to the cursor.
BindStaticParameters( )	N/A	Binds parameters to a statement.
GetCursor( )	AcDBCursor	Gets the database cursor object associated with this data source.
GetDBConnection( )	AcDBConnection	Gets the database connection against which this data source will run.
OpenCursor( )	N/A	Opens a cursor on a statement.


See also

Class AcDataAdapter

Class AcDataRow

Class AcDataSource

Class AcSqlQuerySource


Methods for class AcDatabaseSource

AcDatabaseSource::BindDataRow method

AcDatabaseSource::BindStaticParameters method

AcDatabaseSource::GetCursor method

AcDatabaseSource::GetDBConnection method

AcDatabaseSource::OpenCursor method


AcDatabaseSource::BindDataRow method

Example

Binds the data row to the cursor.

Syntax

Sub BindDataRow( cursor As AcDBCursor )

cursor

The cursor to which to bind the data row.

Description

If you subclass AcDatabaseSource, you must override the BindDataRow( ) method to set up the binding between the row fetched by the cursor and the data row class that your subclass instantiates.

The following figure shows the binding relationship between columns in the row returned by the cursor and variables in the data row you defined.


Example

The following example shows:

1	A SELECT statement for which you create a cursor.

2	A data row you define to store values returned by the cursor.

3	The BindDataRow( ) code that binds the data returned by the cursor to the data row.

' SELECT statement

SELECT fname, lname FROM Customer

' Data row definition

Class CustomerRow Subclass of AcDataRow

Dim FirstName As String

Dim LastName As String

End Class

' BindDataRow( ) code

Sub BindDataRow( cursor As AcDBCursor )

cursor.BindColumn( 1, "CustomerRow", "FirstName" )

cursor.BindColumn( 2, "CustomerRow", "LastName" )

End Sub


AcDatabaseSource::BindStaticParameters method

Example

Binds the static parameters, if any, to a cursor for the statement.

Syntax

Sub BindStaticParameters( cursor As AcDBCursor )

cursor

The cursor to which to bind the parameters.

Description

The OpenCursor( ) method of AcDatabaseSource calls BindStaticParameters( ) to bind parameters, if any, to the cursor for a SQL statement. You must override this method if your SQL statement uses parameters.


Example

The following example shows:

1	A SELECT statement that uses a parameter.

2	The BindStaticParameters( ) code that binds the parameter to the statement's cursor.

' SELECT statement

SELECT fname, lname FROM Customers WHERE Customer.State = ?

' BindStaticParameters( ) code

Sub BindStaticParameters( cursor As AcDBCursor )

cursor.BindParameter( 1, "CA" )

EndSub


AcDatabaseSource::GetCursor method

See also

Returns the database cursor associated with the data source.

Syntax

Function GetCursor( ) As AcDBCursor

Description

Call GetCursor( ) to return the database cursor from which the data source will fetch rows. The cursor is available after the Start( ) method calls OpenCursor( ).

To get the associated database statement, call GetStatement( ) from the cursor.

Return value

The database cursor.


See also

AcDBCursor::GetStatement method


AcDatabaseSource::GetDBConnection method

See also

Returns the database connection associated with the data source.

Syntax

Function GetDBConnection( ) As AcDBConnection

Description

Call GetDBConnection( ) to return the database connection associated with the data source. This method is equivalent to GetConnection( ), except the type of the returned connection is the more derived AcDBConnection class. You can use this connection, for example, to raise an error if a database error occurs.

Return value

The database connection.


See also

AcDataAdapter::GetConnection method

Class AcDBConnection


AcDatabaseSource::OpenCursor method

See also

Opens the database cursor.

Syntax

Sub OpenCursor( stmt As String )

Description

The OpenCursor( ) method is a helper method called by your implementation of Start( ). Your Start( ) method must create the SQL statement. Start( ) then calls OpenCursor( ) to prepare the statement, bind the parameters, allocate and open a cursor, and bind the data row to the cursor.

OpenCursor( ) calls BindStaticParameters( ) to bind static parameters to the statement. If your SQL statement already has parameters, you must override BindStaticParameters( ). OpenCursor( ) also calls BindDataRow( ), which you need to override to bind the data row to the cursor.


See also

AcDatabaseSource::BindDataRow method

AcDatabaseSource::BindStaticParameters method


Class AcDataControl

See also   Methods

The base class for controls that display data from data rows.

Description

AcDataControl defines the logic for setting the values of data controls, which display data obtained from the input source. Each data control displays one piece of data, such as a name, a date, a quantity, or a total. To specify what data a data control should display, you assign a value expression to the control's ValueExp property. If you leave this property blank, the default value of the data control is Null. For information about specifying value expressions, see the Building Reports guide.

Actuate provides a different type of data control for each data type: AcTextControl to display string data, AcIntegerControl to display numeric data, AcCurrencyControl to display currency data, AcDoubleControl to display double precision floating-point numbers, and AcDateTimeControl to display dates. These classes derive from AcDataControl.

Factory protocol

The protocol for AcDataControl is the same as AcControl's, except that it adds the capability to set the value of a control.

Method	Task
New( )	Initializes the control
Start( )	Initializes the control
Build( )	Called if the enclosing frame does not have access to a data row.
BuildFromRow( )	Called if the enclosing frame has access to a data row. Sets the value of the control from the data row.
SetValue( )	Called by BuildFromRow( ) to set the value of the control, usually from the expression entered into the ValueExp property in the Component Editor.
OnRow( )	Called by BuildFromRow( ) to let the control do additional, row-specific processing.
SetTocEntry( )	Called by BuildFromRow( ) on the first data row to set the Table of Contents entry for the control from that data row.
Finish( )	Completes the control. If the control contains an aggregate value, such as an average, Finish( ) computes the aggregate from the available data, such as the total amount and row count.
Variables

Variable	Type	Description
BackgroundIsClear	Boolean	A flag that indicates whether the background is transparent.
BackgroundColor	AcColor	Determines the background color of the control.
Border	AcLineStyle	Determines the border, if any to place around the control.
Font	AcFont	Determines the font to use for text in the control
TextPlacement	AcTextPlacement	Determines where to place the text in the control.
Properties

Property	Type	Description
SampleValue	String	A sample value to display in the control in the Design Editor. Ignored in the Factory.
BackgroundIsClear	Boolean	A flag that indicates whether the background is transparent.
BackgroundColor	AcColor	Determines the background color of the control.
Border	AcLineStyle	Determines the border, if any to place around the control.
Font	AcFont	Determines the font to use for text in the control
TextPlacement	AcText Placement	Determines where to place the text in the control.
ValueExp	Expression	An expression that specifies the value of the control.
Methods

Method	Type	Description
Build( )	N/A	Sets the value of the control.
BuildFromRow( )	AcBuild Status	Sets the data value of the control with a value from a data row.
Format( )	String	Returns the format pattern specified in the control's Format property.
IsSummary( )	Boolean	Determines whether the control is an aggregate control.
SetTocEntry( )	N/A	Sets the Table of Contents entry value for the control.
SetValue( )	N/A	Sets the value of the control.


See also

Class AcControl

Class AcCurrencyControl

Class AcDateTimeControl

Class AcDoubleControl

Class AcIntegerControl

Class AcTextControl


Methods for class AcDataControl

AcDataControl::Build method

AcDataControl::BuildFromRow method

AcDataControl::Format method

AcDataControl::IsSummary method

AcDataControl::SetTocEntry method

AcDataControl::SetValue method


AcDataControl::Build method

Example   See also

Sets the value of the control.

Syntax

Sub Build( )

Description

The control's Build( ) method is called (instead of the BuildFromRow( ) method) by the Build( ) method of the frame that contains the control. The frame's Build( ) method is called when the frame is placed in a slot where it does not receive any data rows. For information on when the framework calls a frame's Build( ) method, see AcBaseFrame::Build method.

Build( ) sets the value of a control with data from a source other than a data row. The value could be from an Actuate function call, a method call, a variable, or a constant. By default, Build( ) calls SetValue( ) to set the value of the control.

You can override the data control's Build( ) method to perform custom processing, such as changing the value or property of the control depending on a condition.


Example

In the following example, a text control's Build( ) method is overridden to change the control's data value to a different string and its display text to a different color when Date$( ) returns "04-15-1996". Date$( ) was assigned to the control's ValueExp property at design time.

Sub Build( )

    Super::Build( )

    If DataValue = "04-15-1996" Then

DataValue = "Tax day"

Font.Color = Red

End If

End Sub


See also

AcBaseFrame::Build method

AcDataControl::BuildFromRow method

AcDataControl::SetValue method


AcDataControl::BuildFromRow method

Example   See also

Sets the data value of the control with a value from a data row.

Syntax

Function BuildFromRow( row As AcDataRow ) As AcBuildStatus

row

The row to use in setting the value of the control.

Description

BuildFromRow( ) sets the value of a control, using data from a data row. A control's BuildFromRow( ) method is called by the enclosing frame's BuildFromRow( ) method.

Controls fall into the following three categories, depending on their relationship to a data row:

•	Need no data. Some controls, such as graphic images and lines, require no data from the data row. These controls are called constant controls.

•	Use data from a single row. The most common control is a data control that displays data from a single data row.

•	Use data from multiple rows. Some controls summarize data from a set of rows. These controls are called aggregate controls.

The BuildFromRow( ) method provides a general mechanism for handling all three of these cases. If the control does not need the data row, BuildFromRow( ) returns Finished Building. If the control uses a single row, BuildFromRow( ) sets the control's value and returns Finished Building. If the control uses multiple rows, BuildFromRow( ) returns Continue Building.

You can override a control's BuildFromRow( ) method if you want to perform custom processing, such as changing the value or property of the control depending on a condition.

Controls that use a single data row

If a control uses a single data row, BuildFromRow( ) performs the following tasks:

1	On the first row, BuildFromRow( ) calls SetValue( ) to set the value of the control (if any).

2	BuildFromRow( ) calls SetTocEntry( ) to set the Table of Contents entry for the control.

3	BuildFromRow( ) calls OnRow( ), which you can override to do additional processing on the row.

4	BuildFromRow( ) returns Finished Building.

Controls that need no data rows work as if they need only one row: They just ignore the row. In this case, SetValue( ) does nothing.

Controls that use multiple data rows

Aggregate controls work with any number of rows and summarize data from those rows. For example, an aggregate control might show the minimum, maximum, sum, or average of a group of sales records. In this case, BuildFromRow( ) processes rows a bit differently than in the single row case. On the first row, BuildFromRow( ) calls SetTocEntry( ) to set the Table of Contents entry. For all rows, BuildFromRow( ) calls both SetValue( ) and OnRow( ). For aggregate controls, BuildFromRow( ) always returns Continue Building.

The IsSummary( ) method is the key to determining if the control processes a single row or multiple rows. If IsSummary( ) returns True, then the control processes multiple rows. The Design Editor generates IsSummary( ) based on the value you enter in the ValueExp property for a control.

Return value

The build status: Continue Building or Finished Building.


Example

In the following example, an integer control's BuildFromRow( ) method is overridden so that the data value is displayed in green when it is greater than 20.

Function BuildFromRow( row As AcDataRow ) As AcBuildStatus

    BuildFromRow = Super::BuildFromRow( row )

    If DataValue > 20 Then

Font.Color = green

End If

End Function


See also

AcDataControl::Build method

AcDataControl::SetValue method

AcDataFrame::BuildFromRow method


AcDataControl::Format method

See also

Returns the format pattern specified in the control's Format property.

Syntax

Function Format( ) As String

Description

The framework calls Format( ) to return the format pattern specified in the control's Format property. The Format property accepts any of the format patterns available to the Actuate Basic Format$ function.

Format( ) returns the format pattern as a string. For example, if you specified (@@@) @@@-@@@@ as the format pattern for a text control that displays telephone numbers, Format( ) returns (@@@) @@@-@@@@ as a string. This return value is used by GetText( ) to format the control's value for display.

Return value

The format pattern used to format the control's value.


See also

AcControl::GetText method


AcDataControl::IsSummary method

Determines whether the control is an aggregate control.

Syntax

Function IsSummary( ) As Boolean

Description

IsSummary( ) determines whether the control is an aggregate. Actuate automatically generates IsSummary( ) based on the value of the ValueExp property. If you enter nothing for ValueExp, this method returns False. It also returns False if you enter an expression that does not return aggregates.

If you choose to override SetValue( ) to do custom calculations, you should also override IsSummary( ) to return True if you want to compute an aggregate.

Return value

True if the control is an aggregate control.

False if the control is not an aggregate control.


AcDataControl::SetTocEntry method

Sets the Table of Contents entry value for a control.

Syntax

Sub SetTocEntry( row As AcDataRow )

row

The row to use in setting the Table of Contents entry.

Description

SetTocEntry( ) is called by BuildFromRow( ) to set the Table of Contents entry value for a control. This entry appears in the Table of Contents in the Viewer if you choose to include the control in the Table of Contents. By default, SetTocEntry( ) uses the value assigned to the control's TocValueExp property.

Generally, you do not need to override this method. You can, however, override it if you want to perform custom calculations to obtain the TOC entry value.


AcDataControl::SetValue method

See also

Sets the value of the control.

Syntax

Sub SetValue( row As AcDataRow )

row

The row to use in setting the value of the control.

Description

SetValue( ) is called by the Build( ) and BuildFromRow( ) methods to set the value of the control. SetValue( ) uses the value expression you assign to the ValueExp property to generate the value.

Controls fall into the following three categories, depending on their relationship to a data row:

•	Need no data. Some controls, such as graphic images and lines, require no data from the data row. These controls are called constant controls.

•	Use data from a single row. The most common control is a data control that displays data from a single data row.

•	Use data from multiple rows. Some controls summarize data from a set of rows. These controls are called aggregate controls.

The following table summarizes how SetValue( ) is called:

If the number of rows the control uses is ...	SetValue( ) is called ...
0	Once with row = Nothing.
1	Once with a single row.
n	n times, each time with a different row.
Generally, you do not need to override SetValue( ). If you want to change the value or property of the control depending on a specified condition, override Build( ) or BuildFromRow( ). If, however, you want to take control of the process for setting values, you can override SetValue( ). If you override SetValue( ), you do not need to call Super::SetValue( ).


See also

AcDataControl::Build method

AcDataControl::BuildFromRow method


Class AcDataFilter

See also

The abstract base class for all data filter classes.

Description

AcDataFilter is the base class for the two general types of data filter classes: AcSingleInputFilter and AcMultipleInputFilter. A single-input filter accepts input from one data adapter, processes the data, then passes it to the next data adapter or the report section. A multiple-input filter performs the same tasks, but accepts input from any number of data adapters.

Subclassing AcDataFilter

You generally do not derive directly from AcDataFilter. To customize a data filter, you typically use one of the data filters derived from AcDataFilter, and override the Fetch( ) method to implement the filtering algorithm.


See also

Class AcDataAdapter

Class AcMultipleInputFilter

Class AcSingleInputFilter


Class AcDataFrame

Methods

An abstract base class that defines the logic for how frames work with data rows.

Description

AcDataFrame provides the mechanism for building a frame's contents with values from a data row. These services include passing a data row to each of its contents and accumulating aggregates.

Subclassing AcDataFrame

You generally do not create a subclass of AcDataFrame unless you want to change the way frames build their contents.

Methods

Method	Type	Description
BuildFromRow( )	AcBuildStatus	Sets the data values of controls within a frame with values from a data row.


Methods for class AcDataFrame

AcDataFrame::BuildFromRow method


AcDataFrame::BuildFromRow method

See also

Sets the data values of controls within a frame with values from a data row.

Syntax

Function BuildFromRow( row As AcDataRow ) As AcBuildStatus

row

The data row to use in setting the values of the controls in the frame.

Description

The framework calls BuildFromRow( ) to set the data values of controls within a frame with values from a data row. The frame's BuildFromRow( ) calls BuildFromRow( ) for each of the frame's contents to set the values.

The return value of BuildFromRow( ) indicates whether the frame processed the row. The frame's BuildFromRow( ) method determines its return value based on the return values of each content's BuildFromRow( ) method. The frame uses this return value to decide whether to continue passing rows to its contents, or whether to instantiate a new frame to process a row.

Frames can process either a single row, or an unlimited set of rows.

•	If the frame processes only a single row, then BuildFromRow( ) returns Finished Building after the frame's contents have set their values. This return value indicates to the frame's container that it should instantiate a new frame to process the next data row.

•	If a frame processes multiple rows (perhaps because it contains a graph), then BuildFromRow( ) always returns Continue Building. This return value indicates to the frame's container that it should send all the data rows it gets.

If any one of the frame's contents returns Continue Building, the frame's BuildFromRow( ) method returns Continue Building. This process allows you to mix, for example, a line control (which requires no rows), a text control (which requires one row), and a graph (which processes multiple rows) within a single frame. The controls that process only one row will process only the first row and will ignore all subsequent rows.

You can override a frame's BuildFromRow( ) method to perform custom processing, such as conditionally accepting rows or accepting a limited number of rows.

Return value

The build status: Continue Building or Finished Building.


See also

AcBaseFrame::Build method

AcDataControl::BuildFromRow method


Class AcDataRow

Example   See also   Methods

A class that defines the characteristics of a data row. A data row is a record structure that contains data from a single input record, processed into a format that the report accepts. Typically, each variable in a data row corresponds to a single column (field) of a record.

Description

AcDataRow works with data adapter classes (AcDataSource, AcSingleInputFilter, and AcMultipleInputFilter) to produce formatted data for the report. The data source retrieves data from an input source (database, spreadsheet, or another source) and creates an instance of a subclass of AcDataRow for each record. The data filter filters and sorts the data as needed.

The following figure gives a high-level view of how the data from an input source is processed into data rows and sent to the report. Note that data filters are optional, and you may use multiple data filters.

If you use the Query Editor to build a SQL query, Actuate creates the data row. If you create a custom data source or a custom data filter, you need to create a custom data row that works with the data source or filter.

Data rows are transient. They are created in the Factory, passed to the report, then deleted.

Subclassing AcDataRow

You need to create a subclass of AcDataRow when you create a custom data source or filter.

How to derive from AcDataRow

To derive a subclass from AcDataRow, do the following:

1	Add the variables that represent the fields of the data row.

2	Override the OnRead( ) method if you need to compute some of the variable values based on the input fields.


Example

The following is an example of a derived AcDataRow class that defines the variables to hold the result of a query that returns four columns.

Class AccountSummary Subclass of AcDataRow

Dim	AccountName 	As String

Dim 	Address	As String

Dim	CreditLimit 	As Currency

Dim	DueDate	As Date

End Class

Variables

Variable	Type	Description
RowNumber	Integer	The number of this row, starting with 1, within the data source.
Methods

Method	Type	Description
GetValue( )	Variant	Returns the value of the specified column or variable.
OnRead( )	N/A	Called after the associated data adapter has written its output to the data row.


See also

Class AcDataAdapter

Class AcReportComponent

Class AcDataSource


Methods for class AcDataRow

AcDataRow::GetValue method

AcDataRow::OnRead method


AcDataRow::GetValue method

Example   See also

Returns the value of the specified column or variable.

Syntax

Function GetValue( colName As String ) As Variant

colName

The column or variable name whose value to return.

Description

The GetValue( ) method is a general-purpose method that lets you access data within your data row. Conceptually, data rows are composed of columns. Actuate gives you several options for how to define your columns:

•	A data row variable.

•	A table.column alias for a data row variable.

•	A function.

•	A member of a class or structure member variable.

In all cases, simply refer to the column using the string name you pass to GetValue( ). The following discusses each case in detail.

You use GetValue( ) to access columns in a data row within code that is given an object reference to the base AcDataRow class. You can use GetValue( ) as a shorthand to avoid having to convert the AcDataRow reference into a reference to your derived data row class. When you use square-bracket notation within a control's value expression, Actuate translates each name in square brackets into a call to GetValue( ).

Accessing data row variables

The simplest approach is to use GetValue( ) to refer to a data row variable. If you create your data row by hand, then you can use GetValue( ) to look up the value of a variable. Suppose that you have the AccountSummary data row and you want to get the account name. Do the following, where AccountName is the name of a variable in the data row:

Sub SetValue( row As AcDataRow )

DataValue = row.GetValue( "AccountName" )

End Sub

Database column aliases

When you use the Actuate Query Builder to build a query data stream, Actuate automatically builds a data row for you. Actuate also sets up a mapping from database table.column names to data row variables. You can then pass one of these database names to GetValue( ) to obtain the value of the corresponding data row variable.

This feature of GetValue( ) enables dynamic binding; the ability to work with a row at runtime, even if you do not know the exact data type of the row. Suppose that you write code for a control that is to work with a customer name, and you know that this will always be a value from the Name column of the Customer table. You want your control to work with many different queries, and thus many different data rows. To do this, write the following code when you want to obtain the value of the customer name from a data row:

Sub SetValue( row As AcDataRow )

DataValue = row.GetValue( "Customer.Name" )

End Sub

Functions

Sometimes you will create a data row that contains a certain set of columns, but that also needs to provide a set of computations on those columns. For example, if you have a data row for a customer invoice, you might want to know how much of the total amount of that invoice is not yet due, now due, or 30, 60, or 90+ days past due. You could create a set of variables to hold these amounts, but it would be much easier to simply provide a set of methods that perform the calculation as needed. For example,

Function Amount30DaysLate( ) As Currency

If DueDate + 30 <= Date( ) And Date( ) < DueDate + 60 Then

Amount30DaysLate = InvoiceAmount

Else

Amount30DaysLate = 0.0

End If

End Function

You can reference such functions using square bracket notation in value expressions for controls in the Design Editor, or by using the GetValue( ) method. Actuate lets you create functions that act like data row columns as long as those functions:

•	Return one of the variable types listed above.

•	Take no arguments.

For example, the following example lets you access the Amount30DaysLate( ) method:

[Amount30DaysLate]

row.GetValue( "Amount30DaysLate" )

Working with structures and objects

Finally, you can use square bracket notation in a value expression or GetValue( ) in code to access members of structures or objects nested inside the data row.

Order of evaluation

Usually the name you provide to GetValue( ) uniquely identifies one column alias (table.column name), variable, or function. However, if you have both a column alias and a variable or function with the same name, Actuate will choose the column alias.


Example

Suppose that your data row contains an AddressStruct structure that contains FullName, Street, City, State, and Zip variables as follows:

Type AddressStruct

FullName AS String

Street As String

City As String

State As String

Zip As String

End Type

Also, suppose that your customer data row has a variable called Address that is defined to be of type AddressStruct. You can access members of that structure with dot notation as follows:

[Address.FullName]

[Address.Street]

...

row.GetValue( "Address.FullName" )

row.GetValue( "Address.Street" )

...

Similarly, if your data row contains an object reference variable to another object, you can access members of that other object using the same dot syntax.

Of course, you can still convert the AcDataRow variable to point to your particular data row class, then access the variable directly:

Sub SetValue( row As AcDataRow )

Dim accRow As AccountSummary

DataValue = acctRow.AccountName

End Sub

If you, however, access the row variable directly, then your control will work with only one specific kind of data row. That is why the preferred way to access data in a data row is through the GetValue( ) method. Then your code will work with any data row as long as that row has the correct column or variable name.

Return value

The value of the given column or variable.


See also

AcControl::GetValue method


AcDataRow::OnRead method

Example

Called by the data adapter after it creates the data row and sets the data row values.

Syntax

Sub OnRead( )

Description

You can override OnRead( ) to manipulate variables in a data row, for example, to set a calculated variable based on other variables in the data row.


Example

In the following example, the data row's OnRead( ) method is overridden to calculate a value for the ExtendedCost variable. This value is computed from values in two other variables--Cost and Quantity--in the data row.

Sub OnRead( )

Super::OnRead( )

ExtendedCost = Cost * Quantity

End Sub


Class AcDataSection

Methods

An abstract base class that defines the logic sections use to process a group of data rows.

Description

A data section processes a group of data rows. AcDataSection is the base class for the two types of data sections: AcReportSection and AcGroupSection.

A report section defines a group as the entire set of data rows read from a data stream. A group section defines a group as the set of data rows that have the same key value, for example, all data rows whose state field value is "CA." Functionally, the following is the difference between a report section and a group section:

•	A report section opens a data stream and retrieves data rows from it.

•	A group section relies on another component to provide it with data rows.

Both types of data sections can represent HTML tables.

Both types of data sections process groups of data rows the same way. The processing centers on the five component references that AcDataSection defines. The following table describes how the data section processes rows for components in these component references.

Component reference	Description	Process
PageHeader	Contains a frame that appears at the top of each page, but the first.	The data section keeps track of the page and flow start and end events to build the page header frame. The data section passes the current row to the page header frame when the frame is built.
Before	Contains a frame that appears before the first row in a group.	The data section's Start( ) method instantiates the Before frame. The Before frame's BuildFromRow( ) method is called to process each row the section processes. The data section finishes the Before frame after the frame processes the last row in the group.
Content	Contains a component (a section or a frame) that processes each data row in a group.	The data section instantiates the content component when it processes the first row. The component's BuildFromRow( ) method is called to process each row until it returns Finished Building.
After	Contains a frame that appears after the last row in a group.	The data section's Start( ) method instantiates the After frame. The After frame's BuildFromRow( ) method is called to process each row the section processes. The data section finishes the After frame after the frame processes the last row in the group.
PageFooter	Contains a frame that appears at the bottom of each page, but the last.	The data section keeps track of the page and flow start and end events to build the page footer frame. The data section passes the current row to the page footer frame when the frame is built.
The processes described in the previous table explain the process when a data section uses running (or one-pass) aggregates, for example, an After frame that calculates the total orders for a group of rows. The process changes if the section uses lookahead (or two-pass) aggregates, for example, an After frame that calculates the order value for a group or rows as a percentage of all totals, across all groups. In this case, the data section has to process the data rows twice (hence, the term two-pass), the first pass to calculate the aggregates, and the second pass to actually build the contents as described in the table.

AcDataSection defines several methods that process lookahead aggregates: AccumulateAggregate( ), FinishAggregate( ), ContentHasAggregates( ), HasAggregates( ), and IsTwoPass( ).

Subclassing AcDataSection

You generally do not create a subclass of AcDataSection unless you want to change the way data sections process data rows.

Variables

Variable	Type	Description
ContiguousPageFooter	Boolean	Determines if the page footer appears directly under the last frame on the page or at the bottom of the page.
ShowFooterOnLast	Boolean	Determines if the page footer appears on the last page. By default, the page footer appears on every page but the last.
ShowHeaderOnFirst	Boolean	Determines if the page header appears in the first page. By default, the page header appears on every page but the first.
Properties

Property	Type	Description
After	AcReport Component Structure Reference	The component that appears after the last row in a group.
Before	AcReport Component Structure Reference	The component that appears before the first row in a group.
BorderColor	AcColor	The color of the main portion of the HTML table border.
BorderLightColor	AcColor	The color of the highlighted portion of the HTML table border. (Not supported by Netscape.)
BorderDarkColor	AcColor	The color of the shadow portion of the HTML table border. (Not supported by Netscape.)
BorderLineWidth	Integer	The width, in pixels, of the border around the HTML table, and the lines between cells in the table. A value of 0 means no border. If your browser does not support table borders or provides only fixed size borders, it ignores this value.
CellPadding	Integer	The number of pixels between the content of an HTML table cell and the border of the cell.
CellSpacing	Integer	The number of pixels between adjacent HTML table cells.
Content	AcReport Component Structure Reference	The component that processes each row in a group.
ContiguousPage Footer	Boolean Variable	Determines if the page footer appears directly under the last frame on the page or at the bottom of the page.
FillRows	Boolean	If true, AFC creates empty cells for any HTML table cell that contains data.
FixedColumnWidths	Boolean	Determines whether or not the HTML table column widths are set by the AFC or by the web browser.
Margin	AcSize	The number of pixels to insert between the HTML table and surrounding text.
PageBreakBetween	Boolean Function	Determines if the section should start each content (except page headers and footers) at the top of a new page.
PageHeader	AcFrame Structure Reference	The component that appears at the top of each page.
PageFooter	AcFrame Structure Reference	The component that appears at the bottom of each page.
ShowFooterOnLast	Boolean Variable	Determines if the page footer appears on the last page. By default, the page footer appears on every page but the last.
ShowHeaderOnFirst	Boolean Variable	Determines if the page header appears in the first page. By default, the page header appears on every page but the first.
TableAlignment	AcHtml HorizontalAlignment	The horizontal alignment of the HTML table within the browser window. Options are left, center, or right alignment. (Right alignment is an extension on top of the usual HTML options.)
TableColor	AcColor	The background color of all cells in the HTML table. The default is TransparentColor, which is the same color as the overall HTML document. You an override this color for each row or each cell.
TableStyle	AcHtml TableStyle	Specifies how to create a table in an HTML report: HtmlAutomaticTable (let the AFC decide), HtmlNotTable (don't create a table for the section), or HtmlCreateTable (do create a table for the section).
TableWidth	Integer	The width of the HTML table in pixels or as a percentage of the width of the browser window. A value of 0 means the browser will determine the table width at view time.
TableWidthUnits	AcHtml Units	Specifies if the HTML table width should be in pixels or as a percentage of browser window width.
Methods

Method	Type	Description
AccumulateAggregates( )	N/A	Calculates and accumulates two-pass aggregates.
ContentHasAggregates( )	Boolean	Returns True if the component in the Content slot of this component calculates two-pass aggregates.
FinishAggregates( )	N/A	Finishes two-pass aggregates.
GetAfter( )	AcReport Component	Returns the After component, if any, for this section.
GetBefore( )	AcReport Component	Returns the Before component, if any, for this section.
GetPageFooter( )	AcBaseFrame	Returns the current page footer, if any, for this page.
GetPageHeader( )	AcBaseFrame	Returns the current page header, if any, for this page.
HasAggregates( )	Boolean	Returns True if the section computes two-pass aggregates.
IsTwoPass( )	Boolean	Returns True if the section needs to process the data rows twice.
NewAfter( )	AcReport Component	Instantiates the component in the After slot.
NewBefore( )	AcReport Component	Instantiates the component in the Before slot.
NewContent( )	AcReport Component	Instantiates the component in the Content slot.
NewPageFooter( )	AcBaseFrame	Instantiates the component in the PageFooter slot.
NewPageHeader( )	AcBaseFrame	Instantiates the component in the PageHeader slot.
OnEmptyGroup( )	N/A	Called if the section processed no rows.
PageBreakBetween( )	Boolean	Returns True if the PageBreakBetween property is set.
ShowEmptyHtml Columns( )	Boolean	Return True to create empty columns that act as spacers for columns containing controls. False is the default.
Considerations for HTML reports

HTML documents are all one long page.  HTML does not support the concept of page breaks.  Therefore, properties that control pagination in Actuate reports are ignored when generating HTML for a report.  For this class, the specific properties ignored by HTML reports are

•	PageHeader

•	PageFooter

•	ShowHeaderOnFirst

•	ShowHeaderOnLast

•	PageBreakBetween


Methods for class AcDataSection

AcDataSection::AccumulateAggregates method

AcDataSection::ContentHasAggregates method

AcDataSection::FinishAggregates method

AcDataSection::GetAfter method

AcDataSection::GetBefore method

AcDataSection::GetPageFooter method

AcDataSection::GetPageHeader method

AcDataSection::HasAggregates method

AcDataSection::IsTwoPass method

AcDataSection::NewAfter method

AcDataSection::NewBefore method

AcDataSection::NewContent method

AcDataSection::NewPageFooter method

AcDataSection::NewPageHeader method

AcDataSection::OnEmptyGroup method

AcDataSection::PageBreakBetween method

AcDataSection::ShowEmptyHtmlColumns method


AcDataSection::AccumulateAggregates method

See also

Calculates and accumulates two-pass aggregates.

Syntax

Sub AccumulateAggregates( row As AcDataRow )

row

The data row to process.

Description

The data section calls AccumulateAggregates( ) with each data row to calculate and store the aggregate values. This is done in the first pass of the data row processing. In the second pass, the data section builds the frames and controls that display the aggregate values.

The framework generates AccumulateAggregates( ), and you generally do not override it unless you want to change the process. If you override AccumulateAggregates( ), you must also override HasAggregates( ) to return True. This ensures the data section processes the data rows twice. In addition, you might need to override FinishAggregates( ).


See also

AcDataSection::HasAggregates method

AcDataSection::FinishAggregates method


AcDataSection::ContentHasAggregates method

See also

Returns whether the component in the Content slot of the data section computes two-pass aggregates.

Syntax

Function ContentHasAggregates( ) As Boolean

Description

The data section calls ContentHasAggregates( ) to determine if a content component uses a two-pass aggregate. If it does, ContentHasAggregates( ) returns true. The value that ContentHasAggregates( ) returns affects the value that IsTwoPass( ) returns. If ContentHasAggregates( ) returns true, IsTwoPass( ) returns true. The data section uses these return values to control whether it executes the one- or two-pass process.

Return value

True if the component in the Content slot of this component computes two-pass aggregates.

False if the component in the Content slot of this component does not compute two-pass aggregates.


See also

AcDataSection::IsTwoPass method


AcDataSection::FinishAggregates method

See also

Finishes two-pass aggregates.

Syntax

Sub FinishAggregates( )

Description

The data section calls FinishAggregates( ) when it completes the first-pass process. FinishAggregates( ) performs final processing on aggregates such as averages.

The framework generates FinishAggregates( ), and you generally do not override it unless you want to change the process. If you override FinishAggregates( ), you must also override HasAggregates( ) to return True. This ensures the data section processes the data rows twice.


See also

AcDataSection::HasAggregates method

AcDataSection::AccumulateAggregates method


AcDataSection::GetAfter method

See also

Returns the component in the After slot.

Syntax

Function GetAfter( ) As AcReportComponent

Description

Call GetAfter( ) to get a reference to the component instantiated in the After slot. You need a reference to the component if, for example, you want to change properties of the After component after it has been built.

Return value

The component in the After slot, if any.

Nothing if there is no component in the After slot.


See also

AcDataSection::GetBefore method

AcDataSection::GetPageFooter method

AcDataSection::GetPageHeader method


AcDataSection::GetBefore method

See also

Returns the component in the Before slot.

Syntax

Function GetBeforeFrame( ) As AcReportComponent

Description

Call GetBefore( ) to get a reference to the component instantiated in the Before slot. You need a reference to the component if, for example, you want to change properties of the Before component after it has been built.

Return value

The component in the Before slot, if any.

Nothing if there is no component in the Before slot.


See also

AcDataSection::GetAfter method

AcDataSection::GetPageFooter method

AcDataSection::GetPageHeader method


AcDataSection::GetPageFooter method

See also

Returns the page footer for the currently active flow.

Syntax

Function GetPageFooter( ) As AcBaseFrame

Description

Call GetPageFooter( ) to get a reference to the PageFooter component in the current flow. You need a reference to the component if, for example, you want to change properties of the PageFooter component after it has been built.

Return value

The page footer for the currently active flow, if any.

Nothing if there is no component in the PageFooter slot.


See also

AcDataSection::GetAfter method

AcDataSection::GetBefore method

AcDataSection::GetPageHeader method


AcDataSection::GetPageHeader method

See also

Returns the page header for the currently active flow.

Syntax

Function GetPageHeader( ) As AcBaseFrame

Description

Call GetPageHeader( ) to get a reference to the PageHeader component in the current flow. You need a reference to the component if, for example, you want to change properties of the PageHeader component after it has been built.

Return value

Returns the page header for the currently active flow, if any.

Nothing if there is no component in the PageHeader slot.


See also

AcDataSection::GetAfter method

AcDataSection::GetBefore method

AcDataSection::GetPageFooter method


AcDataSection::HasAggregates method

See also

Determines whether the section computes two-pass aggregates.

Syntax

Function HasAggregates( ) As Boolean

Description

HasAggregates( ) is called by IsTwoPass( ) and ContentHasAggregates( ) to determine if the data section or its content requires a two-pass process.

If you override AccumulateAggregates( ) or FinishAggregates( ), you must also override HasAggregates( ) to return True. This ensures the data section processes the data rows twice.

Return value

True if this section computes two-pass aggregates.

False if this section does not compute two-pass aggregates.


See also

AcDataSection::AccumulateAggregates method

AcDataSection::ContentHasAggregates method

AcDataSection::FinishAggregates method

AcDataSection::IsTwoPass method


AcDataSection::IsTwoPass method

See also

Returns True if the section needs to process the data rows twice.

Syntax

Function IsTwoPass( ) As Boolean

Description

The data section calls IsTwoPass( ) to determine if a data section needs to process data rows twice. The value that ContentHasAggregates( ) returns affects the value that IsTwoPass( ) returns. If ContentHasAggregates( ) returns true, IsTwoPass( ) returns true. The data section uses these return values to control whether it executes the one- or two-pass process.

Return value

True if the section needs to process the data rows twice.

False if the section needs to process the data rows only once.


See also

AcReportComponent::IsTwoPass method


AcDataSection::NewAfter method

See also

Instantiates the component in the After slot.

Syntax

Function NewAfter( ) As AcReportComponent

Description

The framework calls NewAfter( ) to instantiate the component in the data section's After slot. You can override NewAfter( ) to conditionally instantiate an After component. For example, if you want to display a different After frame depending on the value of a data row variable, you can override NewAfter( ) to write the conditional logic.

Return value

The component instantiated in the After slot.


See also

AcDataSection::NewContent method


AcDataSection::NewBefore method

See also

Instantiates the component in the Before slot.

Syntax

Function NewBefore( ) As AcReportComponent

Description

The framework calls NewBefore( ) to instantiate the component in the data section's Before slot. You can override NewBefore( ) to conditionally instantiate a Before component. For example, if you want to display a different Before frame depending on the value of a data row variable, you can override NewBefore( ) to write the conditional logic.

Return value

The component instantiated in the Before slot.


See also

AcDataSection::NewContent method


AcDataSection::NewContent method

Example   See also

Instantiates the component in the Content slot.

Syntax

Function NewContent( ) As AcReportComponent

Description

The framework calls NewContent( ) to instantiate the component in the data section's Content slot. You can override NewContent( ) to conditionally instantiate a Content component. For example, if you want to display a different frame depending on the value of a data row variable, you can override NewContent( ) to write the conditional logic.


Example

The following example shows how you override NewContent( ) to instantiate one of three frames depending on the type of customer. One frame is for business customers, another for residential customers, and yet another for government customers.

Function NewContent( ) As AcReportComponent

Dim cust As CustomerRow

Set cust = GetCurrentRow( )

Select Case cust.CustType

Case "R"

Set NewContent = New Persistent ResidentialCustomerFrame

Case "S"

Set NewContent = New Persistent BusinessCustomerFrame

Case "G"

Set NewContent = New Persistent GovtCustomerFrame

End Select

End Function

Return value

The component instantiated in the Content slot.


See also

AcDataSection::NewAfter method

AcDataSection::NewBefore method

AcDataSection::NewPageFooter method

AcDataSection::NewPageHeader method


AcDataSection::NewPageFooter method

See also

Instantiates the component in the PageFooter slot. Not applicable for HTML reports.

Syntax

Function NewPageFooter( ) As AcBaseFrame

Description

The framework calls NewPageFooter( ) to instantiate the component in the data section's PageFooter slot. You can override NewPageFooter( ) to conditionally instantiate a PageFooter component. For example, if you want to display a different frame depending on the value of a data row variable, you can override NewPageFooter( ) to write the conditional logic.

Return value

The component instantiated in the PageFooter slot.


See also

AcDataSection::NewContent method


AcDataSection::NewPageHeader method

See also

Instantiates the component in the PageHeader slot. Not applicable for HTML reports.

Syntax

Function NewPageHeader( ) As AcBaseFrame

Description

The framework calls NewPageHeader( ) to instantiate the component in the data section's PageHeader slot. You can override NewPageHeader( ) to conditionally instantiate a PageHeader component. For example, if you want to display a different frame depending on the value of a data row variable, you can override NewPageHeader( ) to write the conditional logic.

Return value

The component instantiated in the PageHeader slot.


See also

AcDataSection::NewContent method


AcDataSection::OnEmptyGroup method

Called if the section processed no data rows.

Syntax

Sub OnEmptyGroup( )

Description

The data section calls OnEmptyGroup( ) when it finishes the current group and the group contains no data rows. Override OnEmptyGroup( ) to perform processing in this situation, for example, to output a custom frame to describe the case, or to raise an error.


AcDataSection::PageBreakBetween method

See also

Returns the value of the PageBreakBetween property. Not applicable for HTML reports.

Syntax

Function PageBreakBetween( ) As Boolean

Description

To determine the page on which to place a completed content, the data section calls PageBreakBetween( ) to return the value of the PageBreakBetween property. If PageBreakBetween( ) returns True, each content starts on a new page. You can override PageBreakBetween to take control of the return value.

Return value

The value of the PageBreakBetween property.


See also

AcSection::PageBreakBefore method

AcSection::PageBreakAfter method


AcDataSection::ShowEmptyHtmlColumns method

Determines whether or not to create empty HTML columns that act as spacers for columns containing controls.

Syntax

Function ShowEmptyHtmlColumns( ) As Boolean

Description

ShowEmptyHtmlColumns( ) applies only to HTML reports. Override ShowEmptyHtmlColumns( ) to specify whether or not you want the current report section to use empty columns as horizontal placeholders or spacers for columns which contain controls.

If the current report section is being rendered as an HTML table and this function returns TRUE, the finished table includes empty columns that act as horizontal spacers. Returning TRUE causes the HTML rendering of the report to look more like the original ROI. However, the resulting HTML table is complex and can confuse some older web browsers.

The default is to exclude spacer columns.

Return value

True to include empty columns as horizontal spacers; False otherwise.


Class AcDataSource

See also   Methods

A base class that defines how data sources--one type of data adapter--retrieve data from an input source and create data rows.

Description

AcDataSource is the base class for data adapters that read data from an input source such as a query, a file, or other external source. AcDataSource adds to the base data adapter class some general functionality that is useful when creating data sources.

AcDataSource defines and maintains a variable, IsAtEnd, that is helpful in keeping track of a data source's state. You can set IsAtEnd to True when your program detects that the data source has read the last input row.

Subclassing AcDataSource

Create a subclass directly from AcDataSource if you need a data source that retrieves data from an input source that is not a database. For example, if your report uses data from a spreadsheet or a text file, you need to create a data source that can read from that file type.

To create a custom data source, you must override at least three methods:

1	Override Start( ) to open your input source (such as a flat file).

2	Override Fetch( ) to read data rows from your input source.

3	Override Finish( ) to close your input source.

For an example of creating a custom data source, see Chapter 9, "Customization examples," in Programming with Actuate.

Variables

Variable	Type	Description
IsAtEnd	Boolean	The status of the data source state.
Methods

Method	Type	Description
HasFetchedLast( )	Boolean	Determines if the data source has fetched the last row.


See also

Class AcDataAdapter

Class AcDataRow

Class AcMultipleInputFilter

Class AcSingleInputFilter


Methods for class AcDataSource

AcDataSource::HasFetchedLast method


AcDataSource::HasFetchedLast method

Determines if the data source has fetched the last row.

Syntax

Function HasFetchedLast( ) As Boolean

Description

HasFetchedLast( ) returns the value of the IsAtEnd variable. It is the responsibility of derived classes to ensure that this variable is set correctly. Instead of calling HasFetchedLast( ) to determine if the data source has retrieved all data rows, it is better to use Fetch( )'s return value. Fetch( ) returns Nothing if all data rows have been retrieved.

HasFetchLast( ) is primarily used when data sources must prevent reading past the end of their input sources.

Return value

True if the data source has retrieved the last data row.

False if there are more data rows to retrieve.


Class AcDateTimeControl

A class you use in the report design to display a date or time.

Description

Use the DateTime control to store and display a date and time numeric value. The value you assign to the control's ValueExp property must be a date type. If, for example, you specify Date$( ) in ValueExp, you get an error because the Date$( ) function returns a string. To get the current date as a date type, use the Now( ) function. Similarly, if the DateTime control gets its value from a data row column, make sure the date is actually a date value and not a string.

AcDateTimeControl defines a DataValue variable to store the date/time value. The framework generates SetValue( ) to set the value in DataValue. SetValue( ) uses the value you assign to the ValueExp property to generate the value. Override SetValue( ) if you want to take control of setting the control's data value.

Variables

Variable	Type	Description
DataValue	Date	Holds the date and time value. The default is Null.


Class AcDBConnection

See also   Methods

A base class that defines the basic protocol for establishing database connections.

Description

AcDBConnection class is the base class for the connection classes--AcDB2Connection, AcInformixConnection, AcMSSQLConnection, AcODBCConnection, AcOracleConnection, AcProgressConnection, and AcSybaseConnection--you use to connect to each supported database.

AcDBConnection defines the basics of connecting to and disconnecting from a database, and the logic for creating the database statement object required to execute SQL statements. For information about database statements, see Class AcDBStatement.

AcDBConnection also defines error-handling methods, such as GetGeneralError( ), GetSpecificError( ), GetGeneralErrorText( ), and GetSpecificErrorText( ). You can call these methods to display error messages when the connect or disconnect operations fail.

Methods

Method	Type	Description
Connect( )	Boolean	Connects to the database.
Disconnect( )	N/A	Disconnects the database.
GetGeneralError( )	Integer	Returns the general error code.
GetGeneralErrorText( )	String	Returns the text of the general error.
GetSpecificError( )	Integer	Returns the specific error code.
GetSpecificErrorText( )	String	Returns the text of the specific error.
Prepare( )	AcDBStatement	Creates a database statement object for a SQL statement.
RaiseError( )	N/A	Raises a general or specific error.


See also

Class AcDBStatement


Methods for class AcDBConnection

AcDBConnection::Connect method

AcDBConnection::Disconnect method

AcDBConnection::GetGeneralError method

AcDBConnection::GetGeneralErrorText method

AcDBConnection::GetSpecificError method

AcDBConnection::GetSpecificErrorText method

AcDBConnection::Prepare method

AcDBConnection::RaiseError method


AcDBConnection::Connect method

Example   See also

Connects to the database.

Syntax

Function Connect( ) As Boolean

Description

When you use one of the database-specific connection classes, the framework calls Connect( ) to establish the connection to the database. Connect( ) uses the connection properties set in the Component Editor to perform this task. If a connection is already open, Connect( ) raises an error.

If you create a custom connection, override Connect( ) to specify the connection parameters. You can also override Connect( ) to perform additional processing at startup, for example to open a log file to track errors.

Return value

True if the connection is established.

False if the connection is not established.


Example

The following example shows how you override Connect( ) to open a file and write error messages to it.

Function Connect( ) As Boolean

Connect = Super::Connect( )

Open "log.txt" For Output As 1

Write #1, GetSpecificErrorText( )

End Function


See also

AcDBConnection::Disconnect method


AcDBConnection::Disconnect method

Example   See also

Disconnects from the database.

Syntax

Sub Disconnect( )

Description

When you use one of the database-specific connection classes, the framework calls Disconnect( ) to close the connection when the data stream has finished retrieving all the data rows from the database. Disconnect( ) is valid only when the connection is active.

You can override Disconnect( ) to perform additional processing just before or after a connection is closed, for example, to close a log file that was opened at startup.


Example

The following example shows how you override Disconnect( ) to close an open file after the connection is closed.

Sub Disconnect( )

    Super::Disconnect( )

    Close #1

End Sub


See also

AcDBConnection::Connect method


AcDBConnection::GetGeneralError method

See also

Returns a general error code.

Syntax

Function GetGeneralError( ) As Integer

Description

Call GetGeneralError( ) to check for error conditions and return a general error code. General error codes are generated by Actuate, and are used for all databases. To return error codes generated by the specific SQL database, use GetSpecificError( ).

The following table lists the general error code constants.

Error Code	Constant
DB_NoError	0
DB_OutOfMemory	1
DB_Specific	2
DB_InvalidLogin	3
DB_InvalidColumn	4
DB_InvalidStatement	5
DB_TimeOut	6
DB_InternalError	7
DB_InvalidParameter	8
DB_DescNotAvailable	9
DB_ParameterNotBound	10
DB_EndOfResults	11
DB_CantConvertParameter	12
DB_NoCurrentConnection	13
DB_CursorNotOpen	14
DB_InvalidDescId	15
DB_InvalidParamId	16
DB_NoColumnInfo	17
DB_VariableDescMismatch	18
Return value

The error code generated by Actuate.


See also

AcDBConnection::GetGeneralErrorText method

AcDBConnection::GetSpecificErrorText method

AcDBConnection::GetSpecificError method


AcDBConnection::GetGeneralErrorText method

See also

Returns a general error message.

Syntax

Function GetGeneralErrorText( ) As String

Description

Call GetGeneralErrorText( ) to check for error conditions and return a description of the error. General error messages are generated by Actuate, and are used for all databases. To return error message generated by the specific SQL database, use GetSpecificErrorText( ).

Return value

The text of the Actuate error code.


See also

AcDBConnection::GetGeneralError method

AcDBConnection::GetSpecificError method

AcDBConnection::GetSpecificErrorText method


AcDBConnection::GetSpecificError method

See also

Returns the error code generated by the SQL database.

Syntax

Function GetSpecificError( ) As Integer

Description

Call GetSpecificError( ) to check for error conditions and return an error code generated by the SQL database. To return general error codes generated by Actuate, use GetGeneralError( ).

Return value

The error code generated by the SQL server.


See also

AcDBConnection::GetGeneralError method

AcDBConnection::GetGeneralErrorText method

AcDBConnection::GetSpecificErrorText method


AcDBConnection::GetSpecificErrorText method

See also

Returns the error message generated by the SQL database.

Syntax

Function GetSpecificErrorText( ) As String

Description

Call GetSpecificErrorText( ) to check for error conditions and return a description of the error generated by the SQL server. To return general error messages generated by Actuate, use GetGeneralErrorText( ).

Return value

The text of the SQL server error code.


See also

AcDBConnection::GetGeneralError method

AcDBConnection::GetGeneralErrorText method

AcDBConnection::GetSpecificError method


AcDBConnection::Prepare method

See also

Creates and prepares a database statement object to execute a SQL statement.

Syntax

Function Prepare( stmtText As String ) As AcDBStatement

Description

If you use the standard SQL query data source to retrieve data from the database, the framework calls Prepare( ) to create and prepare a statement object. If you want to create and execute your own SQL statements, you must call Prepare( ), then call Execute( ) or open a cursor on the statement.

Return value

The database statement that was prepared.

Nothing if there is an error in the statement.


See also

AcDBStatement::Prepare method

AcDBStatement::Execute method


AcDBConnection::RaiseError method

See also

Raises a Basic error for the most recent general or specific error from the database.

Syntax

Sub RaiseError( )

Description

When running a batch program in the Factory, you normally want to stop execution and display an error message if a database error occurs. If your code detects an error condition related to a database, your application can call RaiseError( ) to display an error message and stop execution.


See also

AcConnection::RaiseError method


Class AcDB2Connection

Establishes a connection to a DB2 database.

Use the AcDB2Connection class to establish a connection to a DB2 database. The application must set the DLL path, user name, password, and data source prior to connecting. Once connected, the application should not change these values.

Variables

Variable	Type	Description
DllPath	String	The name of the DLL providing client database.
UserName	String	The client user name for the connection.
Password	String	The client password for the connection.
DataSource	String	The DB2 data source.
Properties

Property	Type	Description
DllPath	String Variable	The name of the DLL providing client database.
Password	String Variable	The client password for the connection.
DataSource	String Variable	The DB2 data source.
UserName	String Variable	The client user name for the connection.


Class AcDBCursor

Methods

A class that provides a Basic interface to a database cursor for a SQL statement.

Description

A database cursor is an identifier associated with a set of rows. The cursor manages the retrieval of rows of data. It also keeps track of the row position in the set as the database sends each row to the data source. SELECT statements that return more than one row of data require a database cursor.

When you use Actuate's SQL query data source to retrieve data, the framework executes all the necessary tasks, including creating an instance of AcDBCursor to manage row retrieval. If, however, you write custom code to handle data retrieval, for example, from a stored procedure, you need to create a connection, a database statement, and a cursor.

The following are the steps for retrieving rows with a cursor.

1	Use a subclass of AcDBConnection to connect to your database.

2	Prepare the statement object using the connection's Prepare( ) method. For more information about database statement objects, see Class AcDBStatement.

3	Create a cursor using the statement's AllocateCursor( ) method.

4	Open the cursor using the cursor's OpenCursor( ) method.

5	Bind the cursor to a data row class using the cursor's BindColumn( ) method.

6	Instantiate a data row to hold the first row of data.

7	Call the cursor's Fetch( ) method to retrieve the first row.

8	Repeat the previous two steps to retrieve each row until Fetch( ) returns False, indicating that the cursor has read all the available rows.

The framework automatically deletes the statement and cursor when they have completed their tasks.

Methods

Method	Type	Description
BindColumn( )	N/A	Binds a database column to a data row variable.
BindParameter( )	Boolean	Binds a database parameter to a data row variable.
CloseCursor( )	N/A	Closes the cursor.
DefineProcedure OutputParameter( )	N/A	Provides the required parameter information when getting data from a stored procedure.
DefineProcedure Return Parameter( )	Boolean	Specify the datatype of a return parameter.
Fetch( )	Boolean	Reads one row from the cursor.
GetConnection( )	AcDBStatement	Returns the connection against which the cursor operates.
GetStatement( )	AcDBStatement	Returns the statement from which the cursor was created.
IsOpen( )	Boolean	Indicates whether the cursor is open or not.
New( )	N/A	Instantiates a cursor.
OpenCursor( )	Boolean	Opens the cursor.
StartNextSet( )	Boolean	Starts a new set of rows within a stored procedure.


Methods for class AcDBCursor

AcDBCursor::BindColumn method

AcDBCursor::BindParameter method

AcDBCursor::CloseCursor method

AcDBCursor::DefineProcedureOutputParameter method

AcDBCursor::DefineProcedureReturnParameter method

AcDBCursor::Fetch method

AcDBCursor::GetConnection method

AcDBCursor::GetStatement method

AcDBCursor::IsOpen method

AcDBCursor::New method

AcDBCursor::OpenCursor method

AcDBCursor::StartNextSet method


AcDBCursor::BindColumn method

Example   See also

Binds a database column to a data row variable.

Syntax

Sub BindColumn( columnID As Integer, className As String, memberName As String )

Sub BindColumn( columnName As String, className As String, memberName As String )

columnID

The index of the column to which to bind the data row variable. The first column has an index of 1. The index of each column is determined by its position in the SELECT clause.

columnName

The name of the column to which to bind the data row variable. The name must be the same as the column name or alias used in the SELECT clause.

className

The name of the data row class. This class is typically a subclass of AcDataRow. You can, however, bind column data to variables in any class.

memberName

The name of the variable in the data row to hold the output data.

Description

Use BindColumn( ) to specify how the framework copies column data to the data row. Call BindColumn( ) repeatedly until you have bound each column to a data row variable. All columns must be bound to variables of a single class.

The following figure shows conceptually how columns are bound to variables. In this case, you would call BindColumn( ) six times.

After binding the columns to the data row variables, call Fetch( ) to retrieve each row from the database.


Example

In the following example, a SELECT statement gets the names of contacts whose last name is Franco. A cursor is required because the SELECT statement returns data rows. The calls to BindColumn( ) set up the association between the columns (using the column index) and the FirstName and LastName variables in MyRow.

Class MyRow

Dim FirstName As String

Dim LastName As String

End Class

Sub Example( connection As AcDBConnection )

Dim stmt As AcDBStatement

Dim cursor As AcDBCursor

Dim row As MyRow

' Prepare the statement

Set stmt = connection.Prepare( "SELECT contact_first, contact_last FROM Customers WHERE contact_last = 'Franco'" )

' Open the cursor

Set cursor = stmt.AllocateCursor( )

' Bind the columns to the data row variables

cursor.BindColumn( 1, "MyRow", "FirstName" )

cursor.BindColumn( 2, "MyRow", "LastName" )

' Instantiate the data row and retrieve data

Do While True

Set row = New MyRow

If Not Cursor.Fetch( row ) Then

Exit Do

End If

' Process the row

Loop

End Sub


See also

AcDBCursor::Fetch method


AcDBCursor::BindParameter method

Binds a cursor parameter to an Actuate Basic variable.

Syntax

Sub BindParameter( parameterID As Integer, var As Any)

Sub BindParameter( parameterName As String, var As Any)

parameterId

The position of the parameter to bind. The first parameter in the statement is position 1, the second is position 2, and so on.

var

The variable to bind to the parameter. Its data type should be appropriate for the parameter.

Description

Use BindParameter( ) to specify how the framework supplies parameter data to data rows. Call BindParameter( ) to bind each cursor parameter to a variable. You must bind all parameters.


AcDBCursor::CloseCursor method

See also

Closes the cursor.

Syntax

Sub CloseCursor( )

Description

Call CloseCursor( ) to close the cursor. Use CloseCursor( ) only if you intend to reopen the same cursor later. Actuate closes the cursor automatically when it deletes the cursor object.


See also

AcDBCursor::OpenCursor method


AcDBCursor::DefineProcedureOutputParameter method

See also

Provides the required parameter information when getting data from a stored procedure.

Syntax

For parameters that only return output:

Sub DefineProcedureOutputParameter( pname As String, tcode As Integer )

For parameters that receive input values and return output:

Sub DefineProcedureOutputParameter( pname As String, tcode As Integer, val as Variant )

pname

The name of the output parameter.

tcode

The Actuate Basic type code that maps to the data type of the stored procedure parameter.

val

The value to pass to a stored procedure output parameter that also takes input.

Description

If your report accesses a stored procedure that uses output parameters, you must call DefineProcedureOutputParameter( ) for each parameter to specify the parameter name and Basic data type that matches the parameter's type. If the parameter both accepts an input value and returns an output value, you must additionally specify the input value to pass.

After defining the stored procedure's output parameters and executing the stored procedure, call GetOutputParameter( ) to get the value of each output parameter.


See also

AcDBCursor::DefineProcedureReturnParameter method


AcDBCursor::DefineProcedureReturnParameter method

Specifies the datatype of a return parameter.

Syntax

Function DefineProcedureReturnParameter( pname As String, tcode As Integer ) As Boolean

Pname

The name of the return parameter.

Tcode

The Actuate Basic type code that maps to the data type of the stored procedure return parameter, for example, V_INTEGER, V_LONG, V_STRING.

Description

Call DefineProcedureReturnParameter( ) to specify the datatype of a return parameter. Valid datatypes include V_CURRENCY, V_DATE, V_DOUBLE, V_INTEGER, V_LONG, V_SINGLE, and V_STRING.

See also

AcDBCursor::DefineProcedureOutputParameter method


AcDBCursor::Fetch method

See also

Retrieves one row from a database cursor.

Syntax

Function Fetch( dataRow As AnyClass ) As Boolean

dataRow

The data row to which the data will be copied. The data row's variables should already have been bound to the columns with BindColumn( ).

Description

Fetch( ) retrieves a single row from the database cursor. To retrieve all rows, execute Fetch( ) in a Do loop. When Fetch( ) has retrieved all rows, it returns False. See AcDataAdapter::Fetch method for an example showing how to use Fetch( ).

Return value

True if a row is available.

False if there are no more rows. If you are reading from a stored procedure that returns more than one set of rows, Fetch( ) returns False at the end of each set.


See also

AcDBCursor::BindColumn method

AcDataAdapter::Fetch method


AcDBCursor::GetConnection method

Returns the connection against which the cursor operates.

Syntax

Function GetConnection( ) As AcDBConnection

Description

Call GetConnection( ) to get a reference to the connection for this cursor. You need this reference if, for example, you want to call the connection's error-handling methods, such as GetGeneralError( ) or GetSpecificError( ).

Return value

The connection this cursor uses.


AcDBCursor::GetStatement method

Returns the database statement for which the cursor was created.

Syntax

Function GetStatement( ) As AcDBStatement

Description

Call GetStatement( ) to get a reference to the statement object for which the cursor was created.

Return value

The statement for which the cursor was created.


AcDBCursor::IsOpen method

See also

Returns whether the database cursor is open.

Syntax

Function IsOpen( ) As Boolean

Description

Call IsOpen( ) to return whether the database cursor is open. The value that IsOpen( ) returns is useful for checking the status of the cursor before closing or reopening it, or before executing a task.

Return value

True if the cursor is open.

False if the cursor is not open.


See also

AcDBStatement::AllocateCursor method

AcDBCursor::OpenCursor method

AcDBCursor::New method


AcDBCursor::New method

See also

Instantiates a cursor.

Syntax

Sub New( stmt As AcDBStatement )

stmt

The database statement object from which to create the cursor.

Description

New( ) is one of two ways to create a cursor. The other way is to call the statement's AllocateCursor( ) method. In the following code snippet, the two Set statements are equivalent.

Sub Example( stmt As AcDBStatement )

Dim cursor1 As AcDBCursor

Dim cursor2 As AcDBCursor

Set cursor1 = stmt.AllocateCursor( )

Set cursor2 = New AcDBCursor( stmt )

End Sub


See also

AcDBStatement::AllocateCursor method


AcDBCursor::OpenCursor method

See also

Opens the database cursor.

Syntax

Function OpenCursor( ) As Boolean

Description

Call OpenCursor( ) after AllocateCursor( ) to open the cursor. You can also call OpenCursor( ) to reopen a cursor previously closed with CloseCursor( ).

Another way to open a cursor is to use the statement's OpenCursor( ) method. The difference between the cursor's OpenCursor( ) method and the statement's OpenCursor( ) method is that the latter both allocates and opens a cursor.

The following code snippet illustrates the two ways to allocate and open a cursor. The code snippet assumes the statement has been created and prepared.

Dim cursor1 As AcDBCursor

Dim cursor2 As AcDBCursor

' Using the cursor's AllocateCursor( ) and OpenCursor( ) methods

Set cursor1 = stmt.AllocateCursor( )

cursor.OpenCursor( )

' Using the statement's OpenCursor( ) method

Set cursor2 = stmt.OpenCursor( )

Return value

True if the cursor is opened successfully.

False if an error occurred.


See also

AcDBCursor::CloseCursor method

AcDBStatement::AllocateCursor method

AcDBStatement::OpenCursor method


AcDBCursor::StartNextSet method

Example

Starts a new set of rows within a stored procedure.

Syntax

Function StartNextSet( ) As Boolean

Description

If you are accessing a stored procedure that returns more than one set of rows, you typically have to call StartNextSet( ) after Fetch( ) has finished retrieving a set. StartNextSet( ) prepares the cursor to read a new set of rows. After calling StartNextSet( ), you go through another process of binding the row columns to variables of a new data row with BindColumn( ), then retrieving rows with Fetch( ).

Return value

True if there is another set of data.

False if there are no more sets of data.


Example

The following example shows how you use a cursor to read rows from a stored procedure that returns two sets of rows.

Sub Example( connection As AcDBConnection )

Dim stmt As AcDBStatement

Dim cursor As AcDBCursor

Dim order As OrderRow

Dim payment As PaymentRow

' Prepare the statement and open the cursor.

Set stmt = connection.Prepare( "CustomerInfo Jones" )

Set cursor = stmt.AllocateCursor( )

cursor.OpenCursor( )

' Prepare for the first set; bind each database column
' to a data row variable.

cursor.BindColumn( 1, "OrderRow", "OrderNumber" )

' <bind other columns>

' Read the first set until Fetch( ) returns False.

Do While True

Set order = New OrderRow

If Not cursor.Fetch( order ) Then

Exit Do

End If

' <Process the order row>

Loop

' Prepare for the second set, then bind each database column
' to a data row variable.

Cursor.StartNextSet( )

Cursor.BindColumn( 1, "PaymentRow", "PaymentDate" )

' <bind other columns>

' Read the second set until Fetch( ) returns False.

Do While True

Set order = New PaymentRow

If Not cursor.Fetch( order ) Then

Exit Do

End If

' <Process the payment row>

Loop

End Sub


Class AcDBStatement

Methods

A class that provides a Basic interface to a SQL statement.

Description

A database statement provides a way to execute a SQL statement. Actuate supports two kinds of database statements. One kind of statement executes and returns no data. Examples of such statements include the SQL CREATE TABLE, INSERT, and UPDATE statements. The other kind of statement executes and returns one or more rows of data. The SELECT statement is a typical example.

A statement that returns more than one row of data requires a database cursor. A database cursor manages the retrieval of rows. For more information about database cursors, see Class AcDBCursor.

When you use Actuate's SQL query data source to retrieve data, the framework executes all the necessary tasks, including creating the database statement. If, however, you want to create and execute other SQL statements, you need to create an instance of AcDBStatement.

The following are the steps for creating and executing a SQL statement that does not return data rows. For steps on executing a SQL statement that returns data rows, see Class AcDBCursor.

1	Establish a connection to the database. You can use the one that a report creates for you, or you can create your own connection.

2	Prepare the statement object using the connection's Prepare( ) method.

3	If the SQL statement accepts parameters whose values are provided later, use BindParameter( ) to bind each parameter to a variable.

4	Execute the statement any number of times by calling Execute( ).

5	Let the framework delete the statement object.

Methods

Method	Type	Description
AllocateCursor( )	AcDBCursor	Creates a cursor to read the rows which the statement returns.
BindParameter( )	Boolean	Binds a statement parameter to a variable.
DefineProcedure InputParameter( )	N/A	Provides the required parameter information when passing parameters to a stored procedure.
DefineProcedure OutputParameter( )	N/A	Provides the required parameter information when getting data from a stored procedure.
DefineProcedure ReturnParameter()	Boolean	Specify the datatype of a procedure's return parameter.
Execute( )	Boolean	Executes the SQL statement.
GetOutputCount( )	Integer	Returns the number of columns in the rows which the SQL statement returns.
GetOutputParameter( )	Variant	Returns the output parameters of a stored procedure by name or position.
GetParameterCount( )	Integer	Returns the number of parameters in the SQL statement.
GetProcedureStatus( )	Integer	Returns a preset value that indicates the status of a stored procedure.
GetStatementText( )	String	Returns the text of the SQL statement previously passed to Prepare( ).
New( )	N/A	Instantiates a statement given a connection.
OpenCursor( )	AcDBCursor	Creates and opens a cursor to use to read the rows which the statement returns.
Prepare( )	Boolean	Prepares a SQL statement.


Methods for class AcDBStatement

AcDBStatement::AllocateCursor method

AcDBStatement::BindParameter method

AcDBStatement::DefineProcedureInputParameter method

AcDBStatement::DefineProcedureOutputParameter method

AcDBStatement::DefineProcedureReturnParameter method

AcDBStatement::Execute method

AcDBStatement::GetOutputCount method

AcDBStatement::GetOutputParameter method

AcDBStatement::GetParameterCount method

AcDBStatement::GetProcedureStatus method

AcDBStatement::GetStatementText method

AcDBStatement::New method

AcDBStatement::OpenCursor method

AcDBStatement::Prepare method


AcDBStatement::AllocateCursor method

See also

Creates a cursor to read the rows that the statement returns.

Syntax

Function AllocateCursor( ) As AcDBCursor

Description

AllocateCursor( ) creates and returns a cursor for a database statement but does not open the cursor. You can then bind the data row to the cursor and call the cursor's OpenCursor( ) method to open the cursor. This technique allows you to reuse a cursor multiple times for the same database statement. Unless you need to reuse a cursor, it is easier to use the statement's OpenCursor( ) method to allocate and open a cursor in one step.

Return value

The database cursor that was created.


See also

AcDBCursor::OpenCursor method

AcDBStatement::OpenCursor method


AcDBStatement::BindParameter method

Example   See also

Binds a statement parameter to a variable.

Syntax

Sub BindParameter( parameterId As Variant, var As Any )

parameterId

The position of the parameter to bind. The first parameter in the statement is position 1, the second is position 2, and so on.

var

The variable to bind to the parameter. Its data type should be appropriate for the parameter.

Description

Use BindParameter( ) to specify how the framework supplies parameter values when executing a SQL statement that accepts parameters. Call BindParameter( ) to bind each statement parameter to a variable. You must bind all parameters.

Before calling BindParameters( ), you should already have created the statement with Prepare( ).


Example

The following example shows how to execute a parametized INSERT statement twice, each time with a different set of parameter values. The example assumes you have established a connection to the database.

Note that you assign values to the local variables, then bind each parameter to the corresponding local variable. To execute the statement again with different values, you must assign the new values to the local variables, and again bind each parameter to the corresponding local variable.

Sub AnExample( connection As AcDBConnection )

Dim statement As AcDBStatement

Dim val1 As Integer

Dim val2 As Integer

' Prepare the statement with two parameters, indicated by :val1 and :val2

Set statement = connection.Prepare( "INSERT INTO MyTable (col1, col2) VALUES (:val1, :val2)" )

If statement Is Nothing Then

MsgBox "Failed to prepare the statement"

MsgBox connection.GetSpecificErrorText( )

Exit Sub

End If

' Assign values to the variables.

val1 = 100

val2 = 200

' Bind each parameter to a variable.

Statement.BindParameter( 1, val1 )

Statement.BindParameter( 2, val2 )

' Execute the statements.

If Not statement.Execute( ) Then

MsgBox "Failed to insert data"

MsgBox connection.GetSpecificErrorText( )

Exit Sub

End If

' Execute the statement again with different parameter values.

val1 = 500

val2 = 600

' Again, bind each parameter to a variable.

Statement.BindParameter( 1, val1 )

Statement.BindParameter( 2, val2 )

If Not statement.Execute( ) Then

MsgBox "Failed to insert data"

MsgBox connection.GetSpecificErrorText( )

Exit Sub

End If

' When this function exits, the framework deletes the statement,
' freeing the statement resources.

End Sub


See also

AcDBStatement::Prepare method


AcDBStatement::DefineProcedureInputParameter method

See also

Provides the required parameter information when passing parameter values to a stored procedure.

Syntax

Sub DefineProcedureInputParameter( pname As String, value as Variant)

pname

The name of the input parameter.

value

The value to pass to the stored procedure.

Description

If your report uses a stored procedure that accepts input parameters, you must call DefineProcedureInputParameter( ) for each parameter to specify the parameter name and value to pass to the stored procedure.


See also

AcDBStatement::DefineProcedureOutputParameter method


AcDBStatement::DefineProcedureOutputParameter method

See also

Provides the required parameter information when getting data from a stored procedure.

Syntax

For parameters that only return output:

Sub DefineProcedureOutputParameter( pname As String, tcode As Integer )

For parameters that receive input values and return output:

Sub DefineProcedureOutputParameter( pname As String, tcode As Integer, val as Variant )

pname

The name of the output parameter.

tcode

The Actuate Basic type code that maps to the data type of the stored procedure parameter.

val

The value to pass to a stored procedure output parameter that also takes input.

Description

If your report accesses a stored procedure that uses output parameters, you must call DefineProcedureOutputParameter( ) for each parameter to specify the parameter name and Basic data type that matches the parameter's type. If the parameter both accepts an input value and returns an output value, you must additionally specify the input value to pass.

After defining the stored procedure's output parameters and executing the stored procedure, call GetOutputParameter( ) to get the value of each output parameter.


See also

AcDBStatement::DefineProcedureInputParameter method

AcDBStatement::GetOutputParameter method


AcDBStatement::DefineProcedureReturnParameter method

Specifies the datatype of a return parameter.

Syntax

Function DefineProcedureReturnParameter( pname As String, Tcode As Integer ) As Boolean

Pname

The name of the return parameter.

Tcode

The Actuate Basic type code that maps to the data type of the stored procedure return parameter, for example, V_INTEGER, V_LONG, V_STRING.

Description

Call DefineProcedureReturnParameter( ) to specify the datatype of a return parameter. Valid datatypes include V_CURRENCY, V_DATE, V_DOUBLE, V_INTEGER, V_LONG, V_SINGLE, and V_STRING.

See also

AcDBStatement::DefineProcedureOutputParameter method


AcDBStatement::Execute method

See also

Executes the SQL statement.

Syntax

Function Execute( ) As Boolean

Description

Call Execute( ) to execute a SQL statement that does not return data. Examples of such SQL statements include CREATE TABLE, INSERT, and UPDATE. To execute a SQL statement, such as SELECT, that returns data, you need to use a cursor instead of Execute( ). For information about creating and using a cursor, see Class AcDBCursor.

Typically, you call Execute( ) for each SQL statement you created and prepared with the connection's Prepare( ) method. You can, however, call Execute( ) any number of times for the same statement if the statement contains parameters. For example, if you want to insert 15 rows into a database, you can use one of two techniques:

•	Create 15 INSERT statements using Prepare( ), then call Execute( ) to execute each statement. The following code snippet creates and executes two INSERT statements.

Set stmt1 = connection.Prepare( "INSERT INTO MyTable (fName, lName)
VALUES ("John", "Smith")" )

stmt1.Execute( )

Set stmt2 = connection.Prepare( "INSERT INTO MyTable (fName, lName)
VALUES ("Nancy", "Alvarez")" )

stmt2.Execute( )

•	Create one INSERT statement with parameters using Prepare( ), bind each parameter to a variable, then call Execute( ) 15 times after assigning different values to the variables. The following code snippet creates one INSERT statement and executes it twice, each time with different parameter values.

Dim firstName As String

Dim lastName As String

Set stmt = connection.Prepare( "INSERT INTO MyTable (fName, lName)
VALUES (:param1, :param2)" )

stmt.BindParameter( 1, firstName )

stmt.BindParameter( 2, lastName )

firstName = "John"

lastName = "Smith"

stmt.Execute( )

firstName = "Nancy"

lastName = "Alvarez"

stmt.Execute( )

Both techniques achieve the same results. The second technique, however, executes more efficiently.

Return value

True if the statement executed successfully.

False if an error occurred. You can call the error-handling methods on AcDBConnection to return the error that occurred.


See also

AcDBConnection::Prepare method

AcDBStatement::BindParameter method


AcDBStatement::GetOutputCount method

Returns the number of columns.

Syntax

Function GetOutputCount( ) As Integer

Description

Use GetOutputCount( ) in conditional code that requires the number of columns in the rows returned by the SQL statement. GetOutputCount( ) is also useful if you prepared a SQL statement that returns all columns in a table, such as SELECT * FROM Customers, and you need to know how many columns will be returned. You can call GetOutputCount( ) any time after the statement has been prepared with Prepare( ).

Return value

The number of columns in the rows which the SQL statement returns.


AcDBStatement::GetOutputParameter method

Example   See also

Returns the value of a stored procedure's output parameter.

Syntax

Function GetOutputParameter( columnName As String ) As Variant

or

Function GetOutputParameter( columnIndex As Integer ) As Variant

columnName

The name of the database column from which the data for the output parameter is fetched. Use this argument for Oracle stored procedures.

columnIndex

The position of the column from which the data for the output parameter is fetched. This argument can be used for Sybase, but not Oracle stored procedures.

Description

Call GetOutputParameter( ) to get the value of each output parameter. You should already have defined each output parameter with DefineProcedureOutputParameter( ).

GetOutputParameter( ) returns a single value. To get rows of data, use the cursor's Fetch( ) method.

Return value

Value of output parameter.


Example

The procedure in the following example executes an Oracle stored procedure that returns two output values. DefineProcedureOutputParameter( ) is called to define the name and type of each output parameter. After executing the stored procedure with Execute( ), GetOutputParameter( ) is called to return the value of each output parameter.

Sub GetSPValues( connection As AcDBConnection )

Dim stmt As AcDBStatement

Dim id As Long

Dim newId As Long

Dim name As Variant

' Prepare the statement to execute the OracleProc stored procedure

Set stmt = connection.Prepare( "BEGIN OracleProc (:id, :name); END;" )

If stmt Is Nothing Then

Print #1 "Failed to prepare statement"

Print #1 connection.GetSpecificErrorText( )

Exit Sub

End If

' Define the first parameter that is both an input and output parameter

id = 20

If stmt.DefineProcedureOutputParameter( "id", V_INTEGER, id ) = 0 Then

Print #1 "Failed to define input/output parameter"

Print #1 connection.GetSpecificErrorText( )

Exit Sub

End If

' Define the second output parameter

If stmt.DefineProcedureOutputParameter( "name", V_STRING ) = 0 Then

Print #1 "Failed to define output parameter"

Print #1 connection.GetSpecificErrorText( )

Exit Sub

End If

' Execute the stored procedure

If stmt.Execute( ) = 0 Then

Print #1 "Failed to execute the OracleProc stored procedure"

Print #1 connection.GetSpecificErrorText( )

Else

Print #1 "OracleProc executed"

End If

' Get the values of the output parameters and write the information to a file

name = stmt.GetOutputParameter( "name" )

newId = stmt.GetOutputParameter( "id" )

Print #1, "Output: name = ", name

Print #1, "Output: id = ", newId

End Sub


See also

AcDBStatement::DefineProcedureOutputParameter method

AcDBStatement::Execute method


AcDBStatement::GetParameterCount method

See also

Returns the number of parameters used in the SQL statement.

Syntax

Function GetParameterCount( ) As Integer

Description

Use GetParameterCount( ) in conditional code that requires the number of parameters used in the SQL statement. You can call GetParameterCount( ) any time after the statement has been prepared with Prepare( ).

Return value

The number of parameters in the SQL statement.


See also

AcDBStatement::BindParameter method


AcDBStatement::GetProcedureStatus method

Returns a preset value that indicates the status of a stored procedure.

Syntax

Function GetProcedureStatus( ) As Integer

Description

If your code runs a stored procedure, you can call GetProcedureStatus( ) to return the status of the stored procedure, if status values were previously defined. GetProcedureStatus( ) is typically used to monitor the proper execution and termination of the stored procedure.

Return value

A preset status value.


AcDBStatement::GetStatementText method

See also

Returns the text of the prepared SQL statement.

Syntax

Function GetStatementText( ) As String

Description

You can call GetStatementText( ) to display the text of the SQL statement you prepared or to check that the prepared statement is in the form you intended. You can call GetStatementText( ) any time after the statement has been prepared with Prepare( ).

Return value

The text of the prepared SQL statement.


See also

AcDBConnection::Prepare method

AcDBStatement::Prepare method


AcDBStatement::New method

See also

Instantiates a statement.

Syntax

Sub New( connection As AcDBConnection )

connection

The connection the statement will use.

Description

New( ) is one of two ways to create a statement. The other way is to call the connection's Prepare( ) method. The difference between the two ways is that the connection's Prepare( ) method creates and prepares a statement, whereas, New( ) only creates the statement. If you use New( ), you need to call the statement's Prepare( ) method after New( ) to prepare the statement.

The following code snippet illustrates the two ways to create and prepare a statement.

Sub Example( connection As AcDBConnection)

Dim stmt1 As AcDBStatement

Dim stmt2 As AcDBStatement

' Using the connection's Prepare( ) method

Set stmt1 = connection.Prepare( "DROP TABLE MyTable" )

' Using the statement's New( ) and Prepare( ) methods

Set stmt2 = New AcDBStatement( connection )

stmt2.Prepare( "DROP TABLE MyTable" )

End Sub


See also

AcDBConnection::Prepare method

AcDBStatement::Prepare method


AcDBStatement::OpenCursor method

See also

Allocates and opens a database cursor.

Syntax

Function OpenCursor( ) As AcDBCursor

Description

Call OpenCursor( ) to allocate and open a cursor for a database statement. Another way to allocate and open a cursor is to use the statement's AllocateCursor( ) method followed by the cursor's OpenCursor( ) method. The following code snippet illustrates the two ways to allocate and open a cursor. The code snippet assumes the statement has been created and prepared.

Dim cursor1 As AcDBCursor

Dim cursor2 As AcDBCursor

' Using the statement's OpenCursor( ) method

Set cursor2 = stmt.OpenCursor( )

' Using the cursor's AllocateCursor( ) and OpenCursor( ) methods

Set cursor1 = stmt.AllocateCursor( )

cursor.OpenCursor( )

If you want to reuse a cursor multiple times for the same database, use AllocateCursor( ) instead.

Return value

The instantiated database cursor.


See also

AcDBStatement::AllocateCursor method

AcDBCursor::OpenCursor method


AcDBStatement::Prepare method

See also

Prepares a SQL statement for execution.

Syntax

Function Prepare( statement As String ) As Boolean

statement

The text of the SQL statement.

Description

Call Prepare( ) to initialize the statement object to work with the SQL statement you provide. Before calling Prepare( ), you need to instantiate the statement with New( ).

Another way to create and prepare a statement is to use the connection's Prepare( ) method. The following code snippet illustrates the two ways to create and prepare a statement.

Sub Example( connection As AcDBConnection)

Dim stmt1 As AcDBStatement

Dim stmt2 As AcDBStatement

' Using the statement's New( ) and Prepare( ) methods

Set stmt2 = New AcDBStatement( connection )

stmt2.Prepare( "DROP TABLE MyTable" )

' Using the connection's Prepare( ) method

Set stmt1 = connection.Prepare( "DROP TABLE MyTable" )

End Sub

Return value

True if the statement executed successfully.

False if an error occurred.


See also

AcDBConnection::Prepare method

AcDBStatement::New method


Class AcDetailGraph

Methods

A subclass of AcGraph that maps data rows directly into points in a graph.

Description

The AcDetailGraph class is a subclass of AcGraph. AcDetailGraph maps data rows directly into points in a graph. It does not summarize data, nor does it map rows into a series.

Use the detail graph to display a scatter chart, and similar graphs that display an unsummarized set of points. To create meaningful line graphs, ensure that the points are sorted from lowest to highest X values.

Methods

Method	Type	Description
AddPoint( )	N/A	Adds a point to the end of the list of points for the graph.
BuildFromRow( )	AcBuildStatus	Gathers the data rows.


Methods for class AcDetailGraph

AcDetailGraph::AddPoint method

AcDetailGraph::BuildFromRow method


AcDetailGraph::AddPoint method

Adds a point to the end of the list of points.

Syntax

Sub AddPoint( X As Double, Y As Double, Label As String)

X

The X-value of the data point.

Y

The Y-value of the data point.

Label

The text of the label for the data point.

Description

Adds a point to the end of the list of points for the graph. This method assumes that there is only one data set.


AcDetailGraph::BuildFromRow method

Gathers the data rows.

Syntax

Function BuildFromRow( row As AcDataRow ) As AcBuildStatus

row

The data row to use.

Description

Gathers the data rows.

Return value

The build status of the data row.


Class AcDoubleControl

A class you use in the report design to display a double-precision real (floating point) number. Not applicable for HTML reports.

Description

Use the AcDoubleControl class to store and display a real number, that is, a number that has a fractional part. If you know the number will always be a whole number (no fractions), use an integer control instead. Operations are faster with integers. If you use an integer control, however, numbers with fractions are rounded to the nearest whole number.

AcDoubleControl defines a DateValue variable to store the double value. The framework generates SetValue( ) to set the value in DataValue. SetValue( ) uses the value expression you assign to the ValueExp property to generate the value. Override SetValue( ) if you want to take control of setting the control's data value.

Variables

Variable	Type	Description
DataValue	Double	Holds the double value. The default is Null.


Class AcEllipseControl

A class you use in the report design to display a circle.

Description

An ellipse is a constant control that is fully defined at design time. The attributes you are likely to set are the color of the ellipse, its size, and the style of the line around the ellipse.

Although the properties of an ellipse are typically set in the Design Editor, you can write code to change its attributes at run time when the Factory builds it. For example, you could change the color of the ellipse depending on the value of another control. To accomplish this task, you can override the ellipse's Build( ) or BuildFromRow( ) method. The Build method you override depends on whether the ellipse is contained in a frame that processes data rows or not. For more information about when Build( ) and BuildFromRow( ) are called, see AcBaseFrame::Build method and AcDataFrame::BuildFromRow method.

Variables

Variable	Type	Description
FillColor	AcColor	The color with which to fill the shape.
LineStyle	AcLineStyle	The style of line to draw around the shape.
Properties

Property	Type	Description
FillColor	AcColor	The color with which to fill the shape.
LineStyle	AcLineStyle	The style of line to draw around the shape. You can set the line's color, its width and type (single, double, dotted, and so on).
Considerations for HTML reports

HTML does not provide an ellipse graphic. Therefore, the ellipse control is not supported in HTML reports. If you include an ellipse control in your design, AFC ignores it when generating the HTML output.


Class AcFlow

See also   Methods

An abstract base class that defines the logic for placing frames in a flow, the printable area of a page.

Description

AcFlow is the abstract base class for AcTopDownFlow, the flow you use in a report design. AcFlow defines the protocol that specifies how subpages, content, header, and footer frames are added to a flow, and how flow space is allocated. Its derived class, AcTopDownFlow, implements the details for executing those tasks.

Factory protocol

Method	Task
Start( )	Prepares the flow for receiving frames.
AddFrame( )	Adds each frame to the flow.
Finish( )	Identifies that the flow has received all the frames that it will get.
Subclassing AcFlow

Create a subclass directly from AcFlow if your report requires a flow other than a top-down flow. For example, you might need a grid layout that flows from left to right. AcFlow defines several methods that you must override to specify implementation details. These methods, called pure virtual methods, are empty in AcFlow.

Variables

Variable	Type	Description
BackgroundColor	AcColor	Specifies the background color of the flow. Default is TransparentColor.
BackgroundIsClear	Boolean	Specifies if the background is transparent.
Border	AcBorder	Specifies the border, if any, to draw around the flow.
Rounding	AcRounding	Specifies if the corners of the flow are rounded.
Margins	AcMargins	The space to allow between the border and the contained frames.
Properties

Property	Type	Description
BackgroundColor	AcColor	Specifies the background color of the flow. Default is TransparentColor.
BackgroundIsClear	Boolean	Specifies if the background is transparent.
Border	AcBorder	Specifies the border, if any, to draw around the flow.
Rounding	AcRounding	Specifies if the corners of the flow are rounded.
Margins	AcMargins	The space to allow between the border and the contained frames.
Methods

Method	Type	Description
AddFooter( )	Boolean	Adds a page footer to the flow.
AddFrame( )	Boolean	Attempts to add a frame to the flow.
AddHeader( )	Boolean	Adds a page header to the flow.
AddSubpage( )	Boolean	Adds a subpage to the flow.
CanFitFrame( )	Boolean	Checks if the control contains enough space to contain the given frame.
GetFreeSpace( )	AcSize	Returns the unused space in the flow.
GetPage( )	AcBaseFrame	Returns the page on which this flow appears.
ReleaseSpace( )	N/A	Releases reserved space back to the flow.
ReserveSpace( )	N/A	Reserves a part of the available space within the flow.
ShiftFooterUp( )	Boolean	Moves the footer so it appears immediately after the last frame in the flow.
Considerations for HTML reports

HTML documents are all one long page.  HTML does not support the concept of page breaks. Therefore, the AFC ignores pagination classes, including this one, when generating HTML for a report.


See also

Class AcBasePage

Class AcTopDownFlow


Methods for class AcFlow

AcFlow::AddFooter method

AcFlow::AddFrame method

AcFlow::AddHeader method

AcFlow::AddSubpage method

AcFlow::CanFitFrame method

AcFlow::GetFreeSpace method

AcFlow::GetPage method

AcFlow::ReleaseSpace method

AcFlow::ReserveSpace method

AcFlow::ShiftFooterUp method


AcFlow::AddFooter method

Adds a page footer frame to the flow. Not applicable for HTML reports.

Syntax

Function AddFooter( footer As AcFrame ) As Boolean

footer

The page footer frame.

Description

Derived classes override AddFooter( ), a pure virtual method in AcFlow, to specify how footer frames are placed at the bottom of the flow. If you create a subclass from AcFlow, you need to override AddFooter( ) to specify the implementation details.

Return value

True if the footer was added to the flow.

False if the footer was not added to the flow.


AcFlow::AddFrame method

See also

Adds the frame to the flow.

Syntax

Function AddFrame( frame As AcFrame ) As Boolean

frame

The frame to add to the flow.

Description

Derived classes override AddFrame( ), a pure virtual method in AcFlow, to specify how frames are placed in the flow. If you create a subclass from AcFlow, you need to override AddFrame( ) to specify the implementation details.

Return value

True if the frame was added to the flow.

False if the frame was not added to the flow.


See also

AcPageList::AddFrame method

AcTopDownFlow::AddFrame method


AcFlow::AddHeader method

Adds a page header frame to the flow.

Syntax

Function AddHeader( header As AcFrame ) As Boolean

header

The page header frame.

Description

Derived classes override AddHeader( ), a pure virtual method in AcFlow, to specify how header frames are placed at the top of the flow. If you create a subclass from AcFlow, you need to override AddHeader( ) to specify the implementation details.

Return value

True if the page header was added to the flow.

False if the page header was not added to the flow.


AcFlow::AddSubpage method

Adds a subpage to the flow.

Syntax

Function AddSubpage( subpage As AcSubpage ) As Boolean

subpage

The subpage to add to the flow.

Description

Derived classes override AddSubPage( ), a pure virtual method in AcFlow, to specify how subpages are placed in the flow. If you create a subclass from AcFlow, you need to override AddSubPage( ) to specify the implementation details.

Return value

True if the subpage was added to the flow.

False if the subpage was not added to the flow.


AcFlow::CanFitFrame method

Checks if the flow contains enough space to contain a frame.

Syntax

Function CanFitFrame( frame As AcBaseFrame ) As Boolean

frame

The frame whose size to check.

Description

Derived classes override CanFitFrame( ), a pure virtual method in AcFlow, to specify how to determine if a frame fits in a flow. If you create a subclass from AcFlow, you need to override CanFitFrame( ) to specify the implementation details.

Return value

True if the frame will fit into the flow.

False if the frame will not fit into the flow.


AcFlow::GetFreeSpace method

Returns the unused space in the flow.

Syntax

Function GetFreeSpace( ) As AcSize

Description

Free space is the area of the flow minus the space occupied by frames in the flow. Derived classes override GetFreeSpace( ), a pure virtual method in AcFlow, to specify how to return the available space. If you create a subclass from AcFlow, you need to override GetFreeSpace( ) to specify the implementation details.

Return value

The amount of unused space, in twips, available in the flow.


AcFlow::GetPage method

See also

Returns the page on which this flow appears.

Syntax

Function GetPage( ) As AcBaseFrame

Description

In derived classes, call GetPage( ) to get a reference to the page that contains the flow. Getting a reference to the page is useful if you want to access the page's methods.

Return value

The page that contains the current flow.


See also

AcPageList::GetPage method

AcReportComponent::GetPage method

AcVisualComponent::GetPage method


AcFlow::ReleaseSpace method

See also

Releases space back to the flow.

Syntax

Sub ReleaseSpace( width As Integer, height As Integer )

width

The width (in twips) of the space to release.

height

The height (in twips) of the space to release.

Description

In derived classes, ReleaseSpace( ) releases back to the flow all or part of the space reserved with ReserveSpace( ). Derived classes override ReleaseSpace( ), a pure virtual method in AcFlow, to specify how to free space. If you create a subclass from AcFlow, you need to override ReleaseSpace( ) to specify the implementation details.

Be careful when using ReleaseSpace( ); if you release too much space, the next frame added to the flow might overlap existing contents of the flow.


See also

AcFlow::ReserveSpace method


AcFlow::ReserveSpace method

See also

Reserves a part of the available space within the flow.

Syntax

Sub ReserveSpace( width As Integer, height As Integer )

width

The width (in twips) of the space to reserve.

height

The height (in twips) of the space to reserve.

Description

Derived classes override ReserveSpace( ), a pure virtual method in AcFlow, to specify how to reserve space. If you create a subclass from AcFlow, you need to override ReserveSpace( ) to specify the implementation details.

In derived classes, you can call ReserveSpace( ) to expand a frame or subpage, or to leave a gap between frames.


See also

AcFlow::ReleaseSpace method


AcFlow::ShiftFooterUp method

Moves the footer so it appears immediately after the last content frame in the flow.

Syntax

Sub ShiftFooterUp( footer As AcFrame )

footer

The page footer frame.

Description

Derived classes override ShiftFooterUp( ), a pure virtual method in AcFlow, to specify where to place a footer frame. If you create a subclass from AcFlow, you need to override ShiftFooterUp( ) to specify the implementation details.

By default, page footers appear at the bottom of the flow. In derived classes, you can call ShiftFooterUp( ) to move a specified footer so that it appears just after the other frames in the flow.


Class AcFrame

Methods

The base class for frames used in a report design.

Description

A frame is a container for visual components such as controls, graphs, and other nested frames. Data controls must be placed in a frame. Constant controls can be placed in a frame or a page.

In a report design, a frame and its contents are typically associated with a data row. For example, if a data row contains name, address, and telephone data, you would place in your report design a frame and three data controls within that frame to display the data.

The framework uses a standard protocol for creating frames, making changes in the design of a report easy. For example, you can easily move a frame from the Content slot to the PageHeader slot of a report section.

You can set margins within a frame to define the viewing area within that frame. The Margins variable defines the space outside the Content Region. The following figure illustrates the components of the Content Region, the margin, and the Border Origin with margins set.

The Content Region can have a border. The figure also illustrates the border layout in relation to the Content Region and Frame.

Considerations for HTML reports

When an AcFrame is rendered as an HTML table, the following properties govern its appearance:

Appearance property	Type	Description
BackgroundColor	AcColor	Determines the color of each cell in the HTML table, unless a control in that cell overrides the color.
Border.Pen	AcLineStyle	Set this property to anything other than NullLine to set a border around the HTML table.
Border.Width	AcLineStyle	Determines the width of the border around the HTML table if Border.Pen is not set to NullLine.
Margins.Top and Margins.Bottom	AcMargins	Determine the amount of whitespace above and below the HTML table.
Margins.Left and Margins.Right	AcMargins	Determine the amount of white space on either side of the table.
Factory protocol

A frame is contained by some other component, such as a section or another frame. The frame's container calls the methods in AcFrame.

Method	Task
New( )	Container instantiates the frame.
Start( )	Container starts the frame.
N/A	Frame instantiates all of its controls and nested frames.
Build( ) BuildFromRow( )	Container builds the frame.
Finish( )	Container finishes the frame. Does any cleanup work.
N/A	Container places the frame on the page.
Viewer Protocol

Task

1	The user decides which page to display. The Viewer then
asks that page to display itself.

2	A page consists of flows that have frames in them. A page
asks the frames to display themselves.

3	A frame asks the controls that it contains to display
themselves.

4	The individual controls within each frame display
themselves.

Subclassing AcFrame

Each time you drag a frame off the palette and drop it into the report design, the Design Editor instantiates a subclass of AcFrame. You can use the Method Editor to override methods in the derived class to do special processing or change default properties of the frame.

Variables

Variable	Type	Description
Margins	AcMargins	The amount of space reserved outside the border. This space is not filled with the background color. The overall frame size as given by the size instance variable includes both the outside and inside margins.
Shadow	AcShadow	The depth and color of the shadow. The default is no shadow.
Rounding	AcRounding	The amount of rounding to apply to the border. The default is no rounding.
Properties

Property	Type	Description
Margins	AcMargins	The amount of space reserved outside the border. This space is not filled with the background color. The overall frame size as given by the size instance variable includes both the outside and inside margins.
Shadow	AcShadow	The depth and color of the shadow. The default is no shadow.
Rounding	AcRounding	The amount of rounding to apply to the border. The default is no rounding.
Methods

Method	Type	Description
AdjustSize( )	N/A	Changes the size of the frame.
GetBorderOrigin( )	AcPoint	Returns the upper left coordinates of the border.
GetBorderRect( )	AcRectangle	Returns the origin and size of the rectangle.
GetBorderSize( )	AcSize	Returns the size of the border.
GetContro( )	AcControl	Return a specific control.
PageBreakAfter( )	Boolean	Returns whether to start a new page after the current frame.
PageBreakBefore( )	Boolean	Returns whether to start a new page before the current frame.


Methods for class AcFrame

AcFrame::AdjustSize method

AcFrame::GetBorderOrigin method

AcFrame::GetBorderRect method

AcFrame::GetBorderSize method

AcFrame::GetControl method

AcFrame::PageBreakAfter method

AcFrame::PageBreakBefore method


AcFrame::AdjustSize method

Changes the size of the frame.

Syntax

Sub AdjustSize( )

Description

Override AdjustSize( ) to change the size of a frame after it has been built but before it is added to a page. You can, for example, expand the frame to show additional controls, or contract the frame to hide empty controls.


AcFrame::GetBorderOrigin method

See also

Returns the upper left coordinates of the border.

Syntax

Function GetBorderOrigin( ) As AcPoint

Description

The origin coordinates are the upper-left position of the border.

Return value

The origin coordinates of the border.


See also

AcFrame::GetBorderRect method

AcFrame::GetBorderSize method


AcFrame::GetBorderRect method

See also

Returns the origin and size of the Content Area.

Syntax

Function GetBorderRect( ) As AcRectangle

Description

The rectangle defines the size and position of the border.

Return value

The upper left coordinates and the size of the border.


See also

AcFrame::GetBorderOrigin method

AcFrame::GetBorderSize method


AcFrame::GetBorderSize method

See also

Returns the size of the Content Area.

Syntax

Function GetBorderSize ( ) As AcSize

Description

The size of the rectangle is the space that it takes up within a frame.

Return value

The size, in twips, of the Content Area.


See also

AcFrame::GetBorderOrigin method

AcFrame::GetBorderSize method


AcFrame::GetControl method

Locates a control given the name of that control.

Syntax

Function GetControl( controlName As String ) As AcControl

controlName

The name of the control to find.

Description

You can uniquely identify a control within a frame by its fully-qualified name. This capability makes it easy to access and manipulate controls, for example, conditionally add or remove controls in a frame. Fully-qualified names have the form MyDesign::MyFrame::MyControl.

This method is similar to the AcBaseFrame::FindContentByClass method.

Return value

The specified control, if found.

Nothing if the control was not found.

See also

AcBaseFrame::FindContentByClass method


AcFrame::PageBreakAfter method

See also

Returns whether to start a new page after the current frame.

Syntax

Function PageBreakAfter( ) As Boolean

Description

Used when applying the frame to a page. Specifies whether the frame wants to start on a new page or be the last item on an existing page. The Factory ignores these settings for nested frames, pages, and flows. The Factory uses them for any frame placed directly in a flow that contains frames and subpages.

Return value

True if a new page will be started when the current frame is finished.

False if the next frame will be placed on the current page if there is room.


See also

AcFrame::PageBreakBefore method


AcFrame::PageBreakBefore method

See also

Returns whether to start a new page before the current frame.

Syntax

Function PageBreakBefore( ) As Boolean

Description

Used when applying the frame to a page. Specifies whether the frame wants to start on a new page or be the last item on an existing page. The Factory ignores these settings for nested frames, pages, and flows. The Factory uses them for any frame placed directly in a flow that contains frames and subpages.


Example

This example shows how to conditionally set page breaks. To view the code used in this example in a fuller context:

•	Open Examples\detail.rod

•	Choose View→Browse→Library

•	Select the sales.rol library

•	Right click on the PageBreakFrame component

•	Choose the Properties→Methods tab

•	Scroll down to find and inspect the frame's overridden PageBreakBefore method

The OfficeTitleFrame, SalesRepTitleFrame, CustomerTitleFrame, and OrderTitleFrame in the report design are all subclassed from this single PageBreakFrame component.

Suppose that there are many sales reps for any given office, and that in your sales report you want to do a page break before each new sales rep except the first. You want the first rep's information to appear on the same page with the office information.

The detail.rod sample uses the same logic to display information for each office, for sales reps, for customers, and for orders.

The sample performs the same kind of processing in four different contexts. To do this most efficiently, it creates a new class that has the desired behavior, then subclasses it as needed. The code can be maintained in one place.

In this example, put the logic into a frame. The new class is called PageBreakFrame, and it is defined in the sales.rol library.

The PageBreakBefore( ) method returns the value of the PageBreakBefore property. That means you can put conditional logic into the PageBreakBefore( ) method, and return True or False depending on whether or not this is the first frame instance for the current group. This is how to make your report ignore the property setting and use only the programmed setting.

The call to Super::PageBreakBefore( ) is commented out.

Function PageBreakBefore( ) As Boolean

'PageBreakBefore = Super::PageBreakBefore( )

    	 'Insert your code here

Dim myparent As AcDataSection

PageBreakBefore = True

'Inspect the parent of the containing group.

'First assign an object reference.

Set myparent = GetContainer( ).GetContainer( )

'If it is the first row, do not perform a page break.

If myparent.RowCount = 1 Then

PageBreakBefore = False

End If

End Function

The expression GetContainer( ).GetContainer( ) returns the container two levels up in the design's hierarchy of components.

When an instance of the frame OrderTitleFrame (subclassed from PageBreakFrame) evaluates this expression, the result is a handle to a CustomerGroup instance. When an instance of the frame SalesRepTitleFrame evaluates the same expression, the result is a handle to an OfficeGroup instance.

For example, in CustomerGroup, the variable RowCount tells how many orders that CustomerGroup instance has seen. The function of a CustomerGroup instance is to process all the orders for a single customer. If RowCount is 1, this is the first order: you do not want to a page break before the first order. The same logic works for each of the four title frames you subclass from PageBreakFrame.

Return value

True if the frame will start a new page before the current frame is processed.

False if the current frame will be placed on the current page if there is room.


See also

AcFrame::PageBreakAfter method


Class AcGraph

Methods

An abstract base class that defines the core characteristics of all graph types.

Description

AcGraph provides the interface to the Actuate graph engine. It defines the properties of graphs, such as the type and general format of the graph, X-axis and Y-axis attributes, legend information, and so on. It also defines the methods that compute X and Y values, format graph labels, and return information about where a graph is clicked at view time.

The classes you use in a report design--AcDetailGraph, AcSummaryGraph, and AcHLCGraph--derive from AcGraph. These subclasses implement the methods for building graphs from data row. HTML reports treat graphs as .GIF images.

General properties and variables

Property	Type	Description
AxisColor	AcColor	Color of the axis lines.
BackgroundColor	AcColor	Background color of the graph. Ignored if BackgroundIsClear is True.
BackgroundIsClear	Boolean	True if the background of the graph is clear.
GraphBackground Color	AcColor	Color of the rectangle around the graph.
GraphBackground IsClear	Boolean	True if the rectangle around the graph itself (not including titles or the legend) is clear.
GraphBorderStyle	AcGraphBorder Style	Style for the border around the graph:      GraphNoBorder      GraphSolidBorder      GraphDropShadow      GraphShadowAndBorder      GraphRaisedBorder      GraphLoweredBorder
GraphType	AcGraphType	The graph type is one of the following:      Graph2DPie      Graph3DPie      Graph2DBar      Graph3DBar      GraphLine      Graph2DArea      Graph2DScatter      GraphHLC      GraphTape      GRaphOHLC      Graph2DArea      Graph3DArea
GridColor	AcColor	Color of the grid lines superimposed over the graph.
Title properties and variables

Property	Type	Description
AxisTitleFont	AcFont	Font of the X and Y axis titles.
LabelFont	AcFont	Font for the X and Y axis value labels, and of the data labels adjacent to each point.
TitleBackground Color	AcColor	Background color for the rectangle enclosing the title.
TitleBackground IsClear	Boolean	True indicates that the area under the title should be transparent.
TitleFont	AcFont	Font for the graph title.
TitleBorderStyle	AcGraph BorderStyle	Style for the border around the title.      GraphNoBorder      GraphSolidBorder      GraphDropShadow      GraphShadowAndBorder      GraphRaisedBorder      GraphLoweredBorder
TitleText	String	Title that appears above the graph.
Data properties and variables

Property	Type	Description
DataSetCount	Integer	The number of data series. This value is computed when the graph is displayed. When designing the graph, this property contains the number of sample points to show.
PointCount	Integer	The number of points in each data series. This value is computed when the graph is displayed. When designing the graph, this property contains the number of sample points to show.
PointLabelColor	AcColor	The color of the labels displayed for each point.
PointLabelStyle	AcGraphPoint LabelStyle	The style of the labels displayed for each point. Choices are      GraphNoPointLabels      GraphCustomLabels      GraphNumericLabels      GraphColoredNumericLabels      GraphColoredCustomLabels
Points( )	AcGraphPoint	An array of size (PointCount or SeriesCount) that holds the data for each point in the graph. Each point is a structure that has the following members:      X As Double      Y As Double      Z As Double      Label As String (variable only)
SampleMax		Maximum for the sample values. (Property only)
SampleMin		Minimum for the sample values. (Property only)
ValuesColorList		A comma-separated list of color names or RGB values to identify different data series.
X-axis properties and variables

Property	Type	Description
XAxisPosition	AcGraph XAxisPosition	The position of the X-axis:      GraphXAxisAuto      GraphXAxisTop      GraphXAxisBottom
XAxisStyle	AcGraph AxisStyle	The location of the graph origin:      GraphZeroOrigin      GraphAutoOrigin      GraphCustomOrigin
XLabelCount	Integer	The number of X-axis labels in the XLabels( ) array. (Variable only)
XLabelFormat	String	The format string used to create custom X-axis labels.
XLabels( )	String	The X-axis labels. (Variable only)
XLabelsList		A comma-separated list of quoted  X-axis values. (Property only)
XLabelStyle	AcGraphLabel Style	The kind of labels to show along the X-axis:      GraphNoLabels      GraphAutoLabels      GraphCustomLabels      GraphExpressionLabels
XMajorGridStyle	AcLinePen	The style of line to draw for the major grid lines:      SingleLine      DashLine      DotLine      DashDotLine      DashDotDotLine      NullLine
XMajorTickCount	Integer	The number of ticks to display. For graphs with x-values, this is the number of ticks to display. For graphs without x-values, this is the frequency of the ticks (i.e., points per tick).
XMajorTickStyle	AcGraphTick Style	The kind of tick marks to include:      GraphNoTicks      GraphAutoTicks      GraphCustomTicks
XMax	Double	Sets the maximum X-axis limits. This value is computed when the graph is displayed. When the graph is being designed, this value is used for displaying sample data.
XMin	Double	Sets the minimum X-axis limits. This value is computed when the graph is displayed. When the graph is being designed, this value is used for displaying sample data.
XMinorGridStyle	AcLinePen	The style of line to draw for the minor grid lines.
XShowMinorTicks	Boolean	True indicates the graph displays minor tick marks. If so, there will always be five minor tick marks between major tick marks.
XTitleBackGroundColor	AcColor	The background color of the X-axis title.
XTitleBackgroundIsClear	Boolean	True means the X-title background is transparent.
XTitleBorderStyle	AcGraph BorderStyle	The style of the rectangle that encloses the X-axis title. The border styles are      GraphNoBorder      GraphSolidBorder      GraphDropShadow      GraphShadowAndBorder      GraphRaisedBorder      GraphLoweredBorder
XTitle	String	The text of the label to show for the X-axis
XValueSet	AcGraph XValueSet	Indicates how many X-values are available in the Points( ) array.  • GraphDefaultXValues: No X-values are available, the graph should provide default spacing along the X-axis. • GraphXValuePerDataSet: There is one set of X-values provided in the points for the first (or only) data set that apply to all points. • GraphXValuePerPoint: Each point has its own X-value.
XVerticalLabels	Boolean	True to show X-axis labels vertically instead of horizontally.
Y-axis properties and variables

Property	Type	Description
YAxisPosition	AcGraph YAxisPosition	The position of the Y-axis:      GraphYAxisAuto      GraphYAxisLeft      GraphYAxisRight
YAxisStyle	AcGraph AxisStyle	The location of the graph origin:      GraphZeroOrigin      GraphAutoOrigin      GraphCustomOrigin
YLabelCount	Integer	The number of Y-axis labels in the YLabels( ) array. (Variable only)
YLabelFormat	String	The format string used to create custom Y-axis labels.
YLabels( )	String	The set of custom Y-axis labels. If used, it must be of the size given by YMajorTickCount + 1. (Variable only)
YLabelsList		A comma separated list of quoted  Y-axis values. (Property only)
YLabelStyle	AcGraphLabel Style	The kind of labels to show along the X-axis:      GraphNoLabels      GraphAutoLabels      GraphCustomLabels
YMajorGridStyle	AcLineStyle	The style of line to draw for the major grid lines:      SingleLine      DashLine      DotLine      DashDotLine      DashDotDotLine      NullLine
YMajorTick Count	Integer	The number of ticks to display. For graphs with y-values, this is the number of ticks to display. For graphs without y-values, this is the frequency of the ticks.
YMajorTickStyle	AcGraphTick Style	The kind of tick marks to include:      GraphNoTicks      GraphAutoTicks      GraphCustomTicks
YMax	Double	Sets the maximum Y-axis limits. This value is computed when the graph is displayed. When the graph is being designed, this value is used for displaying sample data.
YMin	Double	Sets the minimum Y-axis limits. This value is computed when the graph is displayed. When the graph is being designed, this value is used for displaying sample data.
YMinorGridStyle	AcLineStyle	The style of line to draw for the minor grid lines. The line styles are      GraphDefaultLines      GraphPatternLines      GraphThickLines
YMinorTicks	Boolean	True indicates the graph displays minor tick marks. If so, there will always be five minor tick marks between major tick marks.
YTitleBackGroundColor	AcColor	The background color of the Y-axis title.
YTitleBackgroundIsClear	Boolean	True means the Y-title background is transparent.
YBorderStyle	AcGraphBorder Style	The style of the rectangle that encloses the X-axis title. The border styles are      GraphNoBorder      GraphSolidBorder      GraphDropShadow      GraphShadowAndBorder      GraphRaisedBorder      GraphLoweredBorder
YTitle	String	The text of the label to show for the Y-axis.
YTitleOrientation	AcGraph YOrientation	Determines how the text appears for the Y-axis title. The default is Up, which rotates the text 90 degrees counterclockwise.      GraphYLabelHoriz      GraphYLabelUp      GraphYLabelDown
YVerticalLabels	Boolean	True to show X-axis labels rotated 90 degrees.
Legend properties and variables

Property	Type	Description
LegendBackgroundColor	AcColor	Background color for the legend.
LegendBackgroundIsClear	Boolean	True if the legend is transparent.
LegendColorText	Boolean	True if the legend entries are the same color as the line, point, or bar they identify. False if they are all the color given by LegendFont.Color.
LegendFont	AcFont	The font of the legend labels.
LegendLabelCount	Integer	The number of labels in the LegendLabels( ) array. It should be either 0 or DataSetCount. (Except for pie charts, when it is of the size PointCount.)
LegendLabels( )	String	The set of legend labels. The size of this array is DataSetCount. (Variable only)
LegendLabelsList		A comma-separated list of quoted legend labels that you provide to create custom legend labels.
LegendPosition	AcGraph Legend Position	The position of the legend:      GraphLegendNone      GraphLegendTop      GraphLegendTopRight      GraphLegendTopLeft      GraphLegendLeft      GraphLegendRight      GraphLegendBottomLeft      GraphLegendBottom      GraphLegendBottomRight
LegendSize	Integer	The relative size of the legend from 0 (smallest) to 100 (largest). Size controls the spacing of legend entries.
LegendBorderStyle	AcGraph BorderStyle	The style of box to draw around the legend. The border styles are      GraphNoBorder      GraphSolidBorder      GraphDropShadow      GraphShadowAndBorder      GraphRaisedBorder      GraphLoweredBorder
Graph-specific properties and variables

Property	Type	Description
PointsArePercent	Boolean	Area graphs only. True indicates that the numbers in the points are percentage figures. If False, then the points are absolute numbers.
ShowAsPercent	Boolean	Area graphs and pie charts only. Draws the graph showing the percentage of each data point as the sum of all points in that data set. The area always fills the full graph height.
BarGrouping	AcGraphBar Grouping	Bar chart only. Specifies how the bar chart groups data:      GraphBarNoGrouping      GraphBarCluster      GraphBarClusterZ (3D only)      GraphBarStack      GraphBarStackPercentage
BarOrientation	AcGraphBar Orientation	Bar chart only. Specifies how the bar chart draw the bars.      GraphBarVertical      GraphBarHorizontal      GraphBarHorizontalReversed
LineStyle	AcGraphLine Style	Line graphs only. Identifies the kind of lines to use to plot the data.       SingleLine      DashLine      DotLine      DashDotLine      DashDotDotLine      NullLine
LineStylesList		Line graphs only. A comma-separated list of line styles; one style for each data set. The styles are      SingleLine      DashLine      DotLine      DashDotLine      DashDotDotLine      NullLine (Property only)
ShowSymbols	Boolean	Line, log/lin, lin/log, log/log, and scatter graphs only. True shows symbols for each point.
ShowLines	Boolean	Line, log/lin, lin/log, log/log only. True shows lines connecting the points.
ShowSticks	Boolean	Line, log/lin, lin/log, log/log, and scatter graphs only. True shows lines from the Y-axis to each point.
HLCBarStyle	AcHLCBar Style	HLC and OHLC graphs only. Determines how the graph displays high, low, and close tick marks:      GraphHLCAllBars      GraphHLCThickBars      GraphHLCNoClose      GraphHLCNoBars
LineThickness	Integer	Line and scatter graphs only. Thickness of lines in graph-specific units.
Methods

Method	Type	Description
ComputeLabels( )	N/A	Computes the labels.
ComputeMinMax( )	N/A	Computes the X and Y minimum and maximum values.
FormatXLabel( )	String	Formats an X-label value.
FormatYLabel( )	String	Formats a Y-label value.
GetHitPoint( )	Integer	Returns the value of the category that was clicked at view time.
GetHitSet( )	Integer	Returns the value of the series that was clicked at view time.
GetHitXValue( )	Double	Returns the x-value of the data point that was clicked at view time.
GetHitYValue( )	Double	Returns the Y-value of the data point that was clicked at view time.


Methods for class AcGraph

AcGraph::ComputeLabels method

AcGraph::ComputeMinMax method

AcGraph::FormatXLabel method

AcGraph::FormatYLabel method

AcGraph::GetHitPoint method

AcGraph::GetHitSet method

AcGraph::GetHitXValue method

AcGraph::GetHitYValue method


AcGraph::ComputeLabels method

See also

Computes the labels for the X-axis and Y-axis.

Syntax

Sub ComputeLabels( )

Description

The framework calls ComputeLabels( ) to calculate and format the labels on the X and Y axis. The processing ComputeLabels( ) performs depends on the value of the XLabelStyle and YLabelStyle properties. If you set those properties to GraphCustomLabels, ComputeLabels( ) calls FormatXLabel( ) and FormatYLabel( ), respectively, to format the labels. If you specified a different value for XLabelStyle and YLabelStyle, this method does nothing; the framework will generate default labels.

Override ComputeLabels( ) if you want to change the way labels are computed. If you want to change the way labels are formatted, override FormatXLabel( ) or FormatYLabel( ).


See also

AcGraph::FormatXLabel method

AcGraph::FormatYLabel method


AcGraph::ComputeMinMax method

Computes the minimum and maximum values for each axis.

Syntax

Sub ComputeMinMax( )

Description

This method computes the minimum and maximum values for each axis if not already specified. It computes the values only if you have requested automatic axis scaling. If you want manual scaling, this method does nothing. You must also have already specified x-values for the graph.


AcGraph::FormatXLabel method

See also

Formats a custom X-axis label.

Syntax

Function FormatXLabel( x As Double ) As String

x

The number of the X-axis label to format.

Description

If you set the XLabelStyle property to GraphCustomLabels, ComputeLabels( ) calls FormatXLabel( ) to format each label on the X-axis. By default, FormatXLabel( ) calls the Format$ function and uses the format argument specified in the XLabelFormat property.

Override this method to change the way labels on the X-axis are formatted.

Return value

The formatted string.


See also

AcGraph::ComputeLabels method

AcGraph::FormatYLabel method


AcGraph::FormatYLabel method

See also

Formats a custom Y-axis label.

Syntax

Function FormatYLabel( y As Double ) As String

y

The number of the Y-axis label to format.

Description

If you set the YLabelStyle property to GraphCustomLabels, ComputeLabels( ) calls FormatYLabel( ) to format each label on the Y-axis. By default, FormatYLabel( ) calls the Format$ function and uses the format argument specified in the YLabelFormat property. Override this method to change the way labels on the Y-axis are formatted.

Return value

The formatted string.


See also

AcGraph::ComputeLabels method

AcGraph::FormatXLabel method


AcGraph::GetHitPoint method

See also

Returns the value of the category that was clicked at view time.

Syntax

Function GetHitPoint( ) As Integer

Description

Call GetHitPoint( ) to determine which category a user clicked. You can use this information to execute an action, such as hyperlinking to related data, in response to a mouse event. You typically call GetHitPoint( ) in mouse event methods, such as OnLButtonClk( ) or OnLButtonDblClk( ).

Actuate numbers each category sequentially, starting with 0. The following illustration shows a single-series and a multi-series bar graph, and the value GetHitPoint( ) returns when each bar is clicked. Each bar or set of bars associated with a label on the X-axis is a category.

Return value

The number of the category that was clicked. This number is stored in the first index of the Point( ) array.


See also

AcGraph::GetHitSet method

AcGraph::GetHitXValue method

AcGraph::GetHitYValue method


AcGraph::GetHitSet method

See also

Returns the value of the series that was clicked at view time.

Syntax

Function GetHitSet( ) As Integer

Description

Call GetHitSet( ) to determine which series in a multi-series graph a user clicked. You can use this information to execute an action, such as hyperlinking to related data, in response to a mouse event. You typically call GetHitSet( ) in mouse event methods, such as OnLButtonClk( ) or OnLButtonDblClk( ).

Actuate numbers each series sequentially, starting with 0. In a single-series graph, GetHitSet( ) always returns 0 no matter which data point is clicked because there is only one series. If you want to detect which data point of a single-series graph is clicked, use GetHitPoint( ) instead.

The following illustrations show a single-series and a multi-series bar graph, and the value GetHitSet( ) returns when each bar is clicked.

Return value

The number of the series that was clicked. This number is stored in the second index of the Point( ) array.


See also

AcGraph::GetHitPoint method

AcGraph::GetHitXValue method

AcGraph::GetHitYValue method


AcGraph::GetHitXValue method

See also

Returns the x-value of the data point that was clicked at view time.

Syntax

Function GetHitXValue( ) As Double

Description

Call GetHitXValue( ) to get the X-axis value of the data point in a scatter graph that a user clicked. The value GetHitXValue( ) returns is meaningful only for scatter graphs because the X-axis is used to plot numeric values. Other graph types use the X-axis to represent categories. To detect the category a user clicks, use GetHitPoint( ).

You typically call GetHitXValue( ) in mouse event methods, such as OnLButtonClk( ) or OnLButtonDblClk( ).

The following illustration shows a scatter graph, and the value GetHitXValue( ) returns when each data point is clicked.

Return value

The X-value of the data point that was clicked.


See also

AcGraph::GetHitPoint method

AcGraph::GetHitSet method

AcGraph::GetHitYValue method


AcGraph::GetHitYValue method

See also

Returns the y-value of the data point that was clicked at view time.

Syntax

Function GetHitYValue( ) As Double

Description

Call GetHitYValue( ) to get the Y-axis value of the data point a user clicked. You can use this information to execute an action, such as displaying the value, in response to a mouse event. You typically call GetHitYValue( ) in mouse event methods, such as OnLButtonClk( ) or OnLButtonDblClk( ).

The following illustration shows a bar graph, and the value GetHitYValue( ) returns when each bar is clicked.

Return value

The Y-value of the data point that was clicked.


See also

AcGraph::GetHitPoint method

AcGraph::GetHitSet method

AcGraph::GetHitXValue method


Class AcGroupSection

Methods

This class groups related rows into a section based on a key column.

Description

Reports often contain grouped data, many times with subtotals for each group. For example, a report of customers could group the customers by state. AcGroupSection is the report component that creates groups within your report. Grouping is based on a key column in your data row, which you identify by setting the Key property.

A group section is a data section, and so it inherits the Before, After, Page Header, Page Footer, and Content slots. Use the After slot to create subtotals over your group. Use the Content slot to process each row in the group. The Content can be a frame, or another group section to create a nested group.

You always use a group section with a report section. If that report section uses a query data stream, then the report section ensures that the query sorts the data rows as needed for the group sections. Specifically, the report section tells the query data stream to sort the data based on the columns identified in the Key properties of group sections associated with the report. If you had specified an Order By clause in your query, then the columns you specified appear after the key columns in the modified Order By clause.

To specify a group to use with a query data source, set the Key property to the name of a column in your data row. You must use the database column name, not the Basic variable name in the data row. Actuate ensures the rows are sorted correctly as explained above.

If your data stream is other than a query, you must ensure that the data stream returns the rows sorted in the correct order as needed by the group sections. Actuate cannot automatically sort the rows for you. You must still specify the Key property for each group section, but in this case, the Key property must be the name of a Basic variable in the data row.

If you want to do a level break on a computed value (such as a range of account numbers) or by looking at only a substring within a field (such as the area code portion of a phone number), then you must create a column that represents this value in your data stream. For example, if you are using a query data stream, you must create a computed column to hold the value that you want to be the key.

You can nest group sections. Each group is identified not just by its own key, but by the entire set of keys of any enclosing group sections. For example, suppose you want a list of customers and their orders by state. You create a report to do the query, then an outer group for states, and an inner group for customers. Assume also that your database contains both Alabama and Alaska, and both states have only one customer and both customers have the name "Smith". Actuate will treat the customers as belonging to different groups. That is, the full key of the first customer is ("Alabama", "Smith") and the full key of the second customer is ("Alaska", "Smith"). Another way of thinking about this is that, when an outer group ends, then all nested groups end also.

Variables

Variable	Type	Description
KeyValue	Variant	The value of the key column for the group.
Properties

Property	Type	Description
Key	Expression	The database column that identifies the group.
Methods

Method	Type	Description
BuildFromRow( )	AcBuildStatus	Incrementally adds rows to the group until the group key changes.
GetKey( )	Variant	Gets the key value from a data row.
GetKeyString( )	String	Returns the key value for a group formatted as a string.
SetTocEntry( )	N/A	Computes the Table of Contents label for this section.


Methods for class AcGroupSection

AcGroupSection::BuildFromRow method

AcGroupSection::GetKey method

AcGroupSection::GetKeyString method

AcGroupSection::SetTocEntry method


AcGroupSection::BuildFromRow method

Builds the section.

Syntax

Function BuildFromRow( row As AcDataRow ) As AcBuildStatus

row

The data row to build.

Description

Group sections nest within a report section that reads the rows from a data stream and passes each to its contents by calling the content's BuildFromRow( ) method. The group section uses this method to incrementally build up the group, one row at a time. When the enclosing section calls BuildFromRow( ) on a group section for the first time, the group section creates the Before and, optionally, the Page Header components as described for AcDataSection. Also, on the first row, BuildFromRow( ) calls the generated GetKey( ) method to identify and store the key value that identifies this group.

For each row after the first, BuildFromRow( ) again calls GetKey( ) to determine the key value for that row. If the key value differs from the one that identifies the group, then the row is actually the first row of the next group. In this case, BuildFromRow( ) produces its After component as described by AcDataSection, and returns False without processing the data row. When the enclosing section sees the return value False, it starts a new group section to represent the new data group and passes the data row to that new group.

In summary, BuildFromRow( ) creates its contents as follows:

1	If the row is the first row, BuildFromRow( ) produces the Page Header and Before components as described in AcDataSection. BuildFromRow( ) also records the row's key value.

2	If the row is not the first row, then BuildFromRow( ) compares the row's key value with the recorded key value. If the key values differ, then BuildFromRow( ) produces the After and Page Footer components as described in AcDataSection, and returns False.

3	If there is no current content, then BuildFromRow( ) calls NewContent( ) to create one.

4	Passes the row to the content's BuildFromRow( ) method. If the content accepts the row, then BuildFromRow( ) returns True.

5	Finishes the current content and instantiates a new one by calling NewContent( ).

6	Calls the content's BuildFromRow( ) method. This time, the content must accept the row, then BuildFromRow( ) returns True.

Return value

The status of the build.


AcGroupSection::GetKey method

Extracts the key value from a data row.

Syntax

Function GetKey( row As AcDataRow ) As Variant

row

The data row to use.

Description

The GetKey( ) method extracts the key value for the group from a data row. The framework generates this method for you based on the column you enter in the Key property for the group section.

Return value

The key value for the group.


AcGroupSection::GetKeyString method

Returns the key value as a string.

Syntax

Function GetKeyString( ) As String

Description

The GetKeyString( ) method formats the group's key value as a string.

Return value

The string containing the group's key value.


AcGroupSection::SetTocEntry method

Sets the Table of Contents entry for the data row.

Syntax

Sub SetTocEntry( row As AcDataRow )

row

The data row to use for the Table of Contents entry.

Description

This method is generated for you based on the expression you specify in the TocValueExp property for the group. The default is to use the key value as set by the Key property for the group.


Class AcHLCGraph

Methods

A class you use in the report design to display data in a high-low-close or open-high-low-close graph.

Description

Use the high-low-close or open-high-low-close graph to display a set of Y-axis values per x-axis category, for example, daily high-low-close stock prices, high-low-average temperatures, or other data that can be represented in sets of three or four values.

AcHLCGraph inherits the general attributes of graphs from AcGraph, and defines methods for reading the four values from a single data row and populating the graph with that data. HTML reports treat graphs as .GIF images.

Methods

Method	Type	Description
AddPoint	N/A	Adds a point to the end of the list of points for the graph.
BuildFromRow	AcBuildStatus	Gathers the data rows.


Methods for class AcHLCGraph

AcHLCGraph::AddPoint method

AcHLCGraph::BuildFromRow method


AcHLCGraph::AddPoint method

Adds a point to the end of the list of points.

Syntax

Sub AddPoint( yOpen As Double, yHigh As Double, yLow As Double, yClose As Double, Label As String)

yOpen

The Open Y-value.

yHigh

The high Y-value.

yLow

The low Y-value.

yClose

The close Y-value.

Label

The text of the label for the data point.

Description

Adds a point to the end of the list of points for the graph. This method assumes that there is only one data set. Each data point actually consists of four Y-values; one each for Open, Close, High, and Low.


AcHLCGraph::BuildFromRow method

Gathers the data rows.

Syntax

Function BuildFromRow( row As AcDataRow ) As AcBuildStatus

row

The data row to use.

Description

Gathers the data rows.

Return value

The status of the build.


Class AcHtmlAppletControl

Methods

A class you use in an HTML report design to add a Java applet.

Description

Use AcHtmlAppletControl to add a Java applet to your HTML report.  This description assumes that you are already familiar with Java, and know how to add a Java applet to an HTML document you create manually.

The HTML applet control generates an HTML <applet>...</applet> tag in your HTML report.

The following steps describe how to attach an applet to a report:

1	Drag an applet control from the palette and drop it into the frame where you want the applet to appear.

2	Size the applet. The Developer Workbench uses inches (or twips) to size the applet; the web browser uses pixels. The DWB uses 40 pixels per inch when it generates the HTML height and width attributes for the applet.

3	Set the AppletName name property to the name of the Java class you want to use. This value is equivalent to the HTML Code attribute.

4	Set the CodeBase property to specify the machine and/or directory on which the Java code resides, if it does not reside in the same directory as the report. This value is equivalent to the HTML Codebase attribute.

5	Set the other properties, if required.

6	If your applet requires parameters, override the HtmlParams( ) method to set the value of each parameter. See the HtmlParams( ) method for details.

For more information about building reports with applets, see Chapter 14, "Building HTML reports," in Building Reports.

Notes

The Developer Workbench does not support Java applets. The control is a placeholder.

Size.  HTML requires that the size of an applet window be set using pixels.  However, Actuate controls are sized in twips, which are much smaller than a pixel.  Actuate assumes 40 twips per pixel. As a result, if you set an applet control to be, say, 4,000x4,000 in size, it will appear several inches in size in the Web browser (depending on your monitor), but it will appear only about a quarter-inch in size in the Design Editor.

Parameters.  Most Java applets take one or more parameters.  You must override a method called HtmlParams( ) to specify the parameters.

Design Editor.  The Design Editor cannot display the actual applet.  The control you see in the Designer is a placeholder.

Variables

Variable	Type	Description
Alignment	AcHtmlImage Alignment	Specifies the alignment of the applet window within the flow of text in the report. For descriptions of the alignment options, see AcHtmlImageAlignment in "AFC data types."
AlternateText	String	In browsers that do not support Java applets, specifies the text that appears in place of the applet.
AppletName	String	The name of the Java applet class.
CodeBase	String	The base URL for the applet code.
ErrorText	String	A message to appear in place of the applet window if the Web browser cannot load or start the applet.
Margin	Integer	The number of pixels of horizontal and vertical space between the applet window and the surrounding text.
Size	AcSize	Specifies the height and width of the applet window in pixels.  (Inherited.)
Properties

Property	HTML attribute	Description
Alignment	align=option	Specifies the alignment of the applet window within the flow of text in the report. For descriptions of the alignment options, see AcHtmlImageAlignment in "AFC data types."
AlternateText		In browsers that do not support Java applets, specifies the text that appears in place of the applet.
AppletName	code=name	The name of the Java applet.
CodeBase	codebase="url"	The base URL for the applet code.
ErrorText	alt="text"	A message to appear in place of the applet window if the Web browser cannot load or start the applet.
Margin	hspace=width  vspace=height	The number of pixels of horizontal and vertical space between the applet window and the surrounding text.
Size	height=height  width=width	Specifies the height and width of the applet window in pixels.  (Inherited.)
Methods

Method	Type	Description
HtmlParams( )	N/A	Override this method to specify parameters to the Java applet.
SetParam( )	N/A	Call this method from HtmlParams( ) to specify each parameter.


Methods for class AcHtmlAppletControl

AcHtmlAppletControl::HtmlParams method

AcHtmlAppletControl::SetParam method


AcHtmlAppletControl::HtmlParams method

Specifies the parameters to a Java applet included in a report design.

Syntax

Sub HtmlParams( htmlFile As Integer )

htmlFile

The channel number for the HTML source file being generated.

Description

If the Java applet you include with your report design requires parameters, you must override HtmlParams( ) to specify the parameters. In the code, call SetParam( ) for each parameter.  Each parameter has a name and a value. Your override code should look like the following:

Sub HtmlParams( htmlFile As Integer )

SetParam( htmlFile, "Text", "Partners" )

SetParam( htmlFile, "TxFont", "Helvetica" )

SetParam( htmlFile, "TxHorizCenter", "true" )

SetParam( htmlFile, "TxVertCenter", "true" )

SetParam( htmlFile, "TxStyle", "Bold" )

SetParam( htmlFile, "TxPointSize", "36" )

SetParam( htmlFile, "TxDelayBetweenRuns", "250" )

...

End Sub

The htmlFile parameter is required. The second parameter to SetParam( ) is the name of your applet parameter, and the third is the value. You must always pass the value as a string. SetParam( ) generates the HTML
<param name=... value="..."> tag.


AcHtmlAppletControl::SetParam method

Specifies each parameter to a Java applet included in a report design.

Syntax

Sub SetParam( htmlFile As Integer, param As String, value As String )

htmlFile

The channel number for the HTML source file being generated.

param

The name of the parameter.

value

The value of the parameter.

Description

Call SetParam( ) from your override of HtmlParams( ) to specify each parameter in your applet.  You must pass the parameter value as a string, even if that value need not be within quotation marks in an HTML value=val attribute.

For a description and example of how to use SetParam( ), see the HtmlParams( ) method.


Class AcHtmlFrame

Methods

A frame that represents one or more lines of text in an HTML report.

Description

Use AcHtmlFrame as the container for controls that display text in an HTML report. For example, you can use an HTML frame to create an HTML header, list, or plain text. AcHtmlFrame adds an HtmlStyle property for specifying the following HTML text formats:

•	Headers 1 though 6

•	Ordered (numbered) list

•	Unordered (bulleted) list

•	Table

•	Plain text

You can use the standard frame (AcFrame) in an HTML report. However, AcHtmlFrame provides HTML-specific properties for formatting lines of text.

When an AcFrame is rendered as an HTML table, the following properties govern its appearance:

Appearance property	Type	Description
BackgroundColor	AcColor	Determines the color of each cell in the HTML table, unless a control in that cell overrides the color).
Border.Pen	AcLineStyle	Set this property to anything other than NullLine to set a border around the HTML table.
Border.Width	AcLineStyle	Determines the width of the border around the HTML table if Border.Pen is not set to NullLine.
Margins.Top and Margins.bottom	AcMargins	Determine the amount of whitespace above and below the HTML table.
Margins.Left and Margins.Right	AcMargins	Determine the amount of white space on either side of the table.
Variables

Variable	Type	Description
FillRow	Boolean	Determines whether or not AFC creates empty cells for any HTML table cell that contains data.
FixedColumn Widths	Boolean	Determines whether or not the HTML table column widths are set by the AFC or by the web browser.
HtmlStyle	AcHtml- FrameStyle	The text style.  Can be any one of the six HTML header levels, standard text, list, table, and so on. The default is HtmlTable.
TextAlignment	AcHtml- Alignment	The horizontal alignment of the text: left, center or right.
Properties

Property	HTML Attribute/Type	Description
FillRow	Boolean	Determines whether or not AFC creates empty cells for any HTML table cell that contains data.
FixedColumn Widths	N/A	Determines whether or not the HTML table column widths are set by the AFC or by the web browser.
HtmlStyle	(varies depending on the chosen style)	The text style.  Can be any one of the six HTML header levels, standard text, list, table, and so on. The default is HtmlTable.
TextAlignment	align=style	The horizontal alignment of the text: left, center or right.
Methods

Method	Type	Description
CanSpanCells( )	Boolean	Determines whether or not a control can span multiple HTML table cells.
GetBlankLineHeight( )	Integer	Determines how much vertical space there can be between two controls before Actuate inserts an HTML blank line between them.
GetMinimumCellSize( )	Integer	Sets the minimum size for table cells when controls overlap.


Methods for class AcHtmlFrame

AcHtmlFrame::CanSpanCells method

AcHtmlFrame::GetBlankLineHeight method

AcHtmlFrame::GetMinimumCellSize method


AcHtmlFrame::CanSpanCells method

Determines whether or not a control can span multiple HTML table cells.

Syntax

Function CanSpanCells( ) As Boolean

Description

CanSpanCells( ) determines whether or not controls in an HTML table can straddle more than one cell. The default is to allow controls to span several cells. Set this method to False if you want to confine controls to one cell.

Return value

True to allow controls to span several cells; False otherwise.


AcHtmlFrame::GetBlankLineHeight method

Determines how much vertical space between two controls results in a blank line in an HTML report.

Syntax

Function GetBlankLineHeight( ) As Integer

Description

GetBlankLineHeight( ) determines the amount of vertical space there can be between two controls in an HTML report before AFC inserts a blank HTML line between them.


AcHtmlFrame::GetMinimumCellSize method

Sets the minimum size for HTML table cells when controls overlap in an HTML report.

Syntax

Function GetMinimumCellSize( ) As Integer

Description

GetMinimumCellSize( ) sets the minimum size, in twips, for HTML table cells when controls overlap in an HTML report. Small minimum cell sizes can result in an HTML table consisting of many narrow columns. Larger minimum cell sizes results in fewer columns and ensures that the controls are vertically aligned.


Class AcHtmlImageControl

A class you use in an HTML report design to display an image.

Description

The HTML image control allows you to place an image into your HTML report. You can also use the standard image control (AcImageControl) in an HTML report. However, AcHtmlImageControl provides HTML-specific properties for manipulating images in HTML.

HTML reports support .GIF and .JPG image files. You can specify other types of graphic files when you design an HTML report, as long as your web browser supports those types of graphic files. During HTML report design, you specify the name of the graphic file, but the file itself is not included until run-time. Graphic files with formats other than .GIF and .JPG do not display in your report design, but they do display when the report runs in your web browser.

Variables

Variable	Type	Description
Alignment	AcHtmlImage Alignment	Specifies the alignment of surrounding text with the image.  To center the image on a line separate from surrounding text, use the Centered option.
AlternateText	String	In browsers that do not support images, specifies the text to display in place of the image.
LowResSourceURL	String	The URL of the initial image to display as the Web browser first loads the page.
MapName	String	The name of the client-side image map associated with the image.  This property takes effect only if MapType is set to a client-side map.
MapType	AcHtmlImage Maptype	Specifies if the image represents a client-side or server-side image map.
Margin	AcSize	Specifies the amount of space, in pixels, between the image and surrounding text.
SourceURL	String	The URL of the image to display.  (See Note about image files.)
UseDefaultSize	Boolean	Determines whether to use the default image size computed by the browser.  If set to True, then AFC does not generate the height and width HTML attributes.  If False, then AFC generates these attributes from the Size property.
Properties

Property	HTML attribute	Description
Alignment	align=opt	Specifies the alignment of surrounding text with the image.  To center the image on a line separate from surrounding text, use the Centered option.
AlternateText	alt="text"	In browsers that do not support images, specifies the text to display in place of the image.
ImageName	src="basename"	The name of the file to display for the image in the DWB.  AFC computes the URL of the image from this name if the SourceURL property is not set.  (See the note below.) (Inherited.)
LowResSourceURL	lowsrc="url"	The URL of the initial image to display as the Web browser first loads the page.
MapName	map="name"	The name of the client-side image map associated with the image.  This property takes effect only if MapType is set to a client-side map.
MapType	ismap	Specifies if the image represents a client-side or server-side image map.
Margin	hspace=width vspace=height	Specifies the amount of space, in pixels, between the image and surrounding text.
Size	height=height width=width	The size of the image, in pixels.  This property takes effect only if UseDefaultSize is set to False.  (Inherited.)
SourceURL	src="url"	The URL of the image to display.  (See the note below.)
UseDefaultSize		Determines whether to use the default image size computed by the browser.  If set to True, then AFC will not generate the height and width HTML attributes.  If False, then AFC generates these attributes from the Size property.
Note about image files

The inherited ImageName property provides the file name of the image to display in the Design Editor, and must be a valid file name for your operating system. The SourceURL property gives the URL that a Web browser uses to access the same file over the Web. If you set both the ImageName and the SourceURL properties, AFC sets the image's src attribute using the value in SourceURL. If you provide only an ImageName without a SourceURL, AFC sets the image's src attribute to the base name of the ImageName. The base name is the file name itself, without the drive and directory path. For example, if ImageName is set to c:/reports/custlist/banner.gif, the base name is "banner.gif". Therefore, AFC generates src="banner.gif" in HTML.


Class AcHtmlObjectControl

The base class for applets, plug-ins, and ActiveX controls.

Description

AcHtmlObjectControl serves as the common superclass for the applet, plug-in, and ActiveX control classes. You generally do not derive directly from AcHtmlObjectControl. It has no methods, properties, or variables associated with it.


Class AcHtmlPlugInControl

Methods

A class you use in an Html report design to add a Netscape plug-in.

Description

The AcHtmlPlugInControl lets you add a Netscape plug-in to your HTML report.  The description that follows assumes you are already familiar with plug-ins, and how to add a plug-in to an HTML document you create manually.  The HTML plug-in control generates an HTML
<embed>...</embed> tag into your HTML report. The following steps describe how to attach a plug-in to a report:

1	Drag a plug-in control from the palette and drop it into the frame where you want the plug-in to appear.

2	Size the plug-in. The Developers Workbench uses inches (or twips) to size the plug-in; the web browser uses pixels. The DWB uses 40 pixels per inch when it generates the HTML height and width attributes for the plug-in.

3	Set the SourceURL property to the name of the file to display in the plug-in. This value is equivalent to the HTML src attribute. Alternatively, set the MimeType property to the MIME type for the plugin if the plug-in does not require a file. This value is equivalent to the HTML type attribute.

4	Optionally set the PlugInPage property to specify the machine and/or directory from which the user can download the plug-in if the plug-in is not already installed on the user's machine. This value is equivalent to the HTML pluginspage attribute.

5	Set the other properties, if required.

6	If the plug-in requires parameters, override the HtmlParams( ) method to set the value of each parameter.  See the HtmlParams( ) method for details.

Notes

The Developer Workbench does not support plug-ins. The control is a placeholder.

Size.  HTML requires that the size of an plug-in window be set using pixels or ens (half the current text point size).  However, Actuate controls are sized in twips which are much smaller than a pixel.  Actuate uses 40 twips per pixel. As a result, if you set a plug-in control to be, say, 4,000x4,000 in size, it will appear several inches in size in the Web browser (depending on your monitor), but it will appear only about a quarter-inch in size in the Design Editor.

Parameters.  Many plug-ins take one or more parameters.  You must override a method called HtmlParams( ) to specify the parameters.

Design Editor.  The Design Editor cannot display the actual plug-in.  The control you see in the Design Editor is simply a placeholder for the actual plugin.

Variables

Variable	Type	Description
Alignment	AcHtmlImage Alignment	The alignment of the plug-in window within the flow of text in the report. For descriptions of the alignment options, see AcHtmlImageAlignment in "AFC data types."
IsHidden	Boolean	Specifies if the plug-in is to be hidden, that is, have no visible window. Check your browser documentation to determine if the browser supports this option.
Margin	AcSize	The number of pixels of horizontal and vertical space between the plug-in window and the surrounding text.
MimeType	String	The MIME type of the plug-in.  Use this for plug-ins that do not require a file.  You must specify either the SourceURL property or the MimeType property, but not both.
PlugInPage	String	The URL of the page from which the user can download the plug-in if the user does not already have it installed.
Size	AcSize	Specifies the height and width of the plug-in window in pixels. This property is inherited.
SizeUnits	AcHtmlPlugIn Units	The type of units to use for the Height and Width properties.
SourceURL	String	A URL that identifies the file to display in the plug-in.
UseForegroundPalette	Boolean	Specifies if the plug-in uses its palette as a foreground palette or a background palette. The default is False.
Properties

Property	HTML attribute	Description
Alignment	align=option	The alignment of the plug-in window within the flow of text in the report. For descriptions of the alignment options, see AcHtmlImageAlignment in "AFC data types."
IsHidden	hidden=opt	Specifies if the plug-in is to be hidden, that is, have no visible window. Check your browser documentation to determine if the browser supports this option.
Margin	hspace=width vspace=height	The number of pixels of horizontal and vertical space between the plug-in window and the surrounding text.
MimeType	type="opt"	The MIME type of the plug-in.  Use this for plug-ins that do not require a file.  You must specify either the SourceURL property or the MimeType property, but not both.
PlugInPage	pluginspage= "url"	The URL of the page from which the user can download the plug-in if the user does not already have it installed.
Size	height=height width=weight	Specifies the height and width of the plug-in window in pixels.  (This property is inherited.)
SizeUnits	units=opt	The type of units to use for the Height and Width properties.
SourceURL	src="name"	A URL that identifies the file to display in the plug-in.
UseForeground-Palette	palette=opt	Specifies if the plug-in uses its palette as a foreground palette or a background palette. The default is False.
Methods

Method	Type	Description
HtmlParams( )	N/A	Override this method to specify parameters to the plug-in application.
SetParams( )	N/A	Call this method from HtmlParams( ) to specify each parameter.


Methods for class AcHtmlPlugInControl

AcHtmlPlugInControl::HtmlParams method

AcHtmlPlugInControl::SetParam method


AcHtmlPlugInControl::HtmlParams method

Specifies the parameters to a plug-in included in a report design.

Syntax

Sub HtmlParams( htmlFile As Integer )

htmlFile

The channel number for the HTML source file being generated.

Description

If the plug-in application you include with your report design requires parameters, you must override HtmlParams( ) to specify the parameters. In the code, call SetParam( ) for each parameter.  Each parameter has a name and a value. Your override code should look like the following:

Sub HtmlParams( htmlFile As Integer )

SetParam( htmlFile, "Loop", "True" )

SetParam( htmlFile, "AutoStart", "True" )

End Sub

The "htmlFile" parameter is required.  The second parameter to SetParam( ) is the name of your plug-in parameter, and the third is the value.  You must always pass the value as a string.  The SetParam( ) method generates the name="value" portion of the HTML <embed...> tag.


AcHtmlPlugInControl::SetParam method

Specifies each parameter to a plug-in application included in a report design.

Syntax

Sub SetParam( htmlFile As Integer, param As String, value As String )

htmlFile

The channel number for the HTML source file being generated.

param

The name of the parameter.

value

The value of the parameter.

Description

Call this method from your override of HtmlParams() to specify each parameter in your plug-in application.  You must pass the parameter value as a string, even if that value need not be within quotation marks in an HTML value=val attribute.

For a description and example of how to use SetParam( ), see the HtmlParams( ) method.


Class AcHtmlReport

Methods

The base class for an HTML report.

Description

If you are designing an HTML report to be viewed through a Web browser, AcHtmlReport is the class you place in the topmost position of the report design in the structure pane. AcHtmlReport defines the general characteristics of an HTML report and the logic for generating HTML reports.

The HTML report adds an additional processing step in the Factory to generate the HTML file or files that make up the report.  First, the Factory creates the standard .ROI file.  The HTML report then makes another pass over the report to generate HTML output.  The generated HTML files are independent of the .ROI file.

Variables

Variable	Type	Description
BackgroundColor	AcColor	The color name or value for the background of the page.  The default is TransparentColor, which uses the default set through the Web browser.
BackgroundImage	String	The URL of an image to display as the background for the page.
BackgroundSound	String	The URL of a sound file that plays when the user views the page.
BackgroundStyle	AcHtmlBack groundStyle	Specifies if the background image scrolls or is fixed as the page scrolls.
BaseFontSize	Integer	The relative size of the base font for the HTML page. Valid values are 1 to 7. The default is 2.
LinkColor	AcColor	The color of links which the user has not yet visited. The default is TransparentColor, which uses the default set through the Web browser.
MaxTocDepth	Integer	The maximum number of levels to display in the generated Table of Contents.
PageSize	AcSize	The height and width of the page in pixels.  The value of 0 is special. Width 0 means the full width of the browser window. Height 0 means the entire height of the browser window.
TextColor	AcColor	The color of text on the page. The default is TransparentColor, which uses the default set through the Web browser.
Title	String	The title of the report.  Report titles appear at the top of the report. If the report has a Table of Contents in a separate frame, the title appears only at the top of the report. If the report has a Table of Contents at the top of the report, the title appears once at the top of the Table of Contents, and again at the top of the report.
TocStyle	AcHtmlToc Style	The style of the Table of Contents. The TOC can appear at the top of the report, or in a separate HTML frame, or there can be no TOC. The default style is to have no TOC.
TocWidth	Integer	The width of the TOC frame when the TOC appears in a separate HTML frame.
TocWidthUnits	AcHtml Units	The units to use for the TOC width: either percent of the browser window width, or pixels.
VisitedLinkColor	AcColor	The color of links that have already been visited. The default is TransparentColor, which uses the default set through the Web browser.
Properties

Property	HTML Attribute	Description
BackgroundColor	BGColor=color	The color name or value for the background of the page. The default is TransparentColor, which uses the default set through the Web browser.
BackgroundImage	Background= "url"	The URL of an image to display as the background for the page.
BackgroundSound	BGSound Src="name"	The URL of a sound file that plays when the user views the page.
BackgroundStyle	BGProperties	Specifies if the background image scrolls or is fixed as the page scrolls.
BaseFontSize	<BaseFontSize= number>	The relative size of the base font for the HTML page. Valid values are 1 to 7. The default is 2.
LinkColor	Link=color	The color of links that the user has not yet visited. The default is TransparentColor, which uses the default set through the Web browser.
MaxTocDepth		The maximum number of levels to display in the generated HTML table of contents.
PageSize	TopMargin= height LeftMargin= width	The height and width of the page in pixels.  The value of 0 is special.  A width of 0 means the full width of the browser window.  A height of 0 means the entire height of the browser window.
TextColor	Text=color	The color of text on the page. The default is TransparentColor, which uses the default set through the Web browser.
Title	<Title>title </Title>	The title of the report.  The title usually appears in the Web browser's window title.
TocStyle		The style of the Table of Contents. The TOC can appear at the top of the report, in a separate HTML frame, or as a control anywhere within the report. The default style is to appear as a control.
TocWidth		The width of the TOC frame when the TOC appears in a separate HTML frame.
TocWidthUnits		The units to use for the TOC width: either percent of the browser window width, or pixels.
ShowTitle		Whether or not to display the title of the report in the report, as well as in the web browser's window title.
VisitedLinkColor	VLink=color	The color of links that the user has visited. The default is TransparentColor, which uses the default set through the Web browser.
Methods

Method	Type	Description
GetServerPrefix( )	String	Returns the location of the server on which the HTML report will be deployed.
GetMaximum HtmlTableRows( )	Integer	Controls the default HTML table formatting.
RoiIsTemporary( )	Boolean	Determines whether or not to keep the .ROI that AFC generates as part of generating an HTML report. The default is to keep the .ROI.


Methods for class AcHtmlReport

AcHtmlReport::GetServerPrefix method

AcHtmlReport::GetMaximumHtmlTableRows method

AcHtmlReport::RoiIsTemporary method


AcHtmlReport::GetServerPrefix method

See also

Returns the location of the server on which the HTML report will be deployed.

Syntax

GetServerPrefix( ) As String

Description

GetServerPrefix() affects how the AFC interprets "server://" style hyperlinks in HTML reports. An HTML report does not know where it will be deployed, so you must override this method to give it that information.

The location format is:

http://web_server/acweb/rpt_server.

If the hyperlink includes a server name, that server name is used instead of rpt_server. If the destination location is relative to the root folder of the server, AFC prepends the full server prefix.

The default value is the value which was set in the Web Agent property for the root folder of the Report Encyclopedia.


See also

Class AcDataSection


AcHtmlReport::GetMaximumHtmlTableRows method

See also

Controls the default HTML table formatting.

Syntax

GetMaximumHtmlTableRows( ) As Integer

Description

GetMaximumHtmlTableRows() determines how HTML tables will be formatted. If there are GetMaximumHtmlTableRows() number of detail frames or fewer, the AFC creates tables for group sections. It creates a table for each frame if the group section contains more than this number of detail frames.


See also

Class AcDataSection


AcHtmlReport::RoiIsTemporary method

Determines whether or not to keep the .ROI after AFC generates the HTML report.

Syntax

Function RoiIsTemporary( ) As Boolean

Description

RoiIsTemporary( ) determines whether or not to keep the .ROI generated as part of generating an HTML report. The default is to keep the .ROI (RoiIsTemporary( ) returns True). Override this method to set the return value to False and discard the .ROI.

Return value

True to keep the .ROI; False to discard it.


Class AcHtmlRuleControl

A class you use in an HTML report design to display a horizontal line.

Description

AcHtmlRuleControl represents the horizontal rule <HR> tag in HTML.

HTML provides only horizontal lines.  HTML calls these lines "rules."  If you include a horizontal line in a frame in an HTML report, AFC represents this line as an HTML rule.  If the line is vertical, or at an angle, AFC ignores the line control when generating the HTML output. AFC uses the Position.Y and EndPosition.Y properties to determine if the line is horizontal.  AFC considers the line to be horizontal if these two properties have the same value.

HTML requires that horizontal rules appear on a line by themselves.  If you include a line control in a frame on the same line as text, AFC will place text before the line on one line, the rule on a second line, and text after the rule on a third line.

Use AcHtmlRuleControl to include a horizontal line in an HTML report. You can also use the standard line control (AcLineControl) in an HTML report. However, AcHtmlRuleControl provides HTML-specific properties for formatting the line.

Variables

Variable	Type	Description
Alignment	AcHtmlHorizontal- Alignment	Specifies if the rule is left, center, or right aligned.
NoShade	Boolean	Specifies if the rule is drawn with 3-D shading. If set to true, the rule is drawn without shading. The default is False.
WidthUnits	AcHtmlUnits	Specifies if the width is measured in pixels or as a percentage of the window width.
Properties

Property	HTML attribute	Description
Alignment	align=type	Specifies if the rule is left, center, or right aligned.
NoShade	noshade	Specifies if the rule is drawn with 3-D shading. If set to true, the rule is drawn without shading. The default is False.
Size.Height	size=pixels	The height of the line in pixels. 0 is the default line height. (Inherited.)
Size.Width	width=value	The width of the line. 0 means the entire width of the page. The width is measured either as a percentage of the window width, or in pixels. (Inherited.)
WidthUnits		Specifies if the width is measured in pixels or as a percentage of the window width.


Class AcImageControl

A class you use in the report design to display external images.

Description

Use AcImageControl to display images stored in any of the file formats listed in the table. You must set the image control's FileName property to specify the file name of the image to display. When you open the report document, the Viewer uses the FileName value to locate the image file.

If you distribute a report to users through email or through the Report Encyclopedia, embed the image files in the report. To do so, set the image control's Embedded property to True. If you do not embed images with reports you distribute, an 'X' appears in place of the image.

File Format	Bits Per Pixel
BMP	1
	4, 8, 24 (RLE)
GIF	4
	8
JPG	24
PCX	1
	4
	8,24
TIF	1 (uncompressed)
	CCITT
	Group 3 - 1D & 2D
	Group 4 - Facsimile
	8, 16, 24 (RLE & LZW)
TGA	8, 16, 24 (RLE)
	32 with alpha channel
Variables

Variable	Type	Description
Border	AcLineStyle	The kind of border, if any, to display around the image.
Embedded	Boolean	True means that the bitmap is embedded in the report. The image is copied into the executable during code generation. As a result, the original bitmap file need not be present on the viewing machine. False means that when the report displays the bitmap, it looks at the FileName value to find the file.
FileName	String	The name of an image file to display in this control.
Properties

Property	Type	Description
Border	AcLineStyle	The kind of border, if any, to display around the image.
Embedded	Boolean	True means that the bitmap is embedded in the report. The image is copied into the executable during code generation. As a result, the original bitmap file need not be present on the viewing machine. False means that when the report displays the bitmap, it looks at the FileName value to find the file.
FileName	String	The name of an image file to display in this control.


Class AcInformixConnection

Establishes a connection to an Informix database.

Description

Use the AcInformixConnection class to establish a connection to an Informix database. The application must set the database environment, user name, and password prior to connecting. Once connected, the application should not change these values.

Variables

Variable	Type	Description
DatabaseEnvironment	String	The name of the database and/or server to connect to. Specify either a server and a database, a database server only, or a database only.
DllPath	String	The name of the DLL providing client database.
Password	String	The client password for the connection.
UserName	String	The client user name for the connection.
Properties

Property	Type	Description
DatabaseEnvironment	String	The name of the database and/or server to connect to. Specify either a server and a database, a database server only, or a database only.
DllPath	String Variable	The name of the DLL providing client database. Default is the most common name used for the connectivity DLL provided by Informix.
Password	String	The client password for the connection.
UserName	String	The client user name for the connection.


Class AcIntegerControl

A class you use in the report design to display integer data.

Description

Use AcIntegerControl to store and display whole numbers. Numbers with fractions are rounded to the naarest whole number. If you require the precision of real numbers, use a double control instead.

AcIntegerControl defines a DataValue variable to store the integer value. The framework generates SetValue( ) to set the value in DataValue. SetValue( ) uses the value expression you assign to the ValueExp property to generate the value. Override SetValue( ) if you want to take control of setting the control's data value.

If you want to change the value or properties of the integer control when the Factory is building it, you can override the integer control's BuildFromRow( ) method. For example, you can change the properties of the control depending on the value stored in the DataValue variable. For an example of how to accomplish this task, see AcDataControl::BuildFromRow method.

Variables

Variable	Type	Description
DataValue	Integer	Holds the integer value. The default is Null.


Class AcIterator

Example   Methods

A base class for all list iterators.

Description

AcIterator is the base class for all list iterators. AcSingleListIterator is derived from this base class and is the iterator for singly linked lists. This class provides methods to iterate over a list.

Iterators are valid only when iterating over a collection that does not change. If you create an iterator over a collection, then change the collection, the operation of the iterator is undefined. If your application requires iteration over a collection as it changes, you can create a copy of the collection and iterate over the copy while changing the original collection.

Methods

Method	Type	Description
GetNext( )	AnyClass	Returns the next node in the list.
HasMore( )	Boolean	Returns True if there is another node in the list.
IsDone( )	Boolean	Returns True if there are no more nodes in the list.
Restart( )	N/A	Sets the iterator at the beginning of the list.
SkipForwardTo( )	AnyClass	Moves the iterator to a new node in the list.
SkipTo( )	Integer	Moves the iterator to the given numbered location in the list.


Example

The following example shows how you create a list and traverse it with a list iterator.

Class MyClass

Dim counter As Integer

End Class

Sub Main ( )

Dim list As AcList

Dim obj As MyClass

Dim count As Integer

Dim iterator As AcIterator

' Create a list

Set list = New AcSingleList

' Create an object and add it to the list

Set obj = New MyClass

obj.counter = 1

list.AddToTail( obj )

' Create a second object and append it to the list

Set obj = New MyClass

obj.counter = 2

list.AddToTail( obj )

' Count the number of objects in the list

count = list.GetCount( )

MsgBox "Number of objects in the list: " & count

' Create a list iterator and get each object in the list

Set iterator = New AcSingleListIterator( list )

Do While iterator.HasMore( )

Set obj = iterator.GetNext( )

MsgBox "The position of this object in the list:" & obj.counter

Loop

' Delete the objects from the list

list.RemoveHead( )

list.RemoveHead( )

End Sub


Methods for class AcIterator

AcIterator::GetNext method

AcIterator::HasMore method

AcIterator::IsDone method

AcIterator::Restart method

AcIterator::SkipForwardTo method

AcIterator::SkipTo method


AcIterator::GetNext method

Returns the next node in the list.

Syntax

Function GetNext( ) As AnyClass

Description

This method returns the next node in the list.

Return value

Returns the next node in the list.


AcIterator::HasMore method

Returns whether there is another node in the list.

Syntax

Function HasMore( ) As Boolean

Description

This method determines whether there are more nodes in the list. This method is the inverse of IsDone( ).

Return value

True if there is another node in the list.

False if there are no more nodes in the list.


AcIterator::IsDone method

Returns whether there is another node in the list.

Syntax

Function IsDone( ) As Boolean

Description

This method determine whether there are more nodes in the list. This method is the inverse of HasMore( ).

Return value

True if there are no more nodes in the list.

False if there are still more nodes in the list.


AcIterator::Restart method

Positions the iterator at the first node.

Syntax

Sub Restart( )

Description

Positions the iterator at the first node in the list.


AcIterator::SkipForwardTo method

Skips forward to the node that contains the given object.

Syntax

Sub SkipForwardTo( obj As AnyClass )

Description

Advances the iterator to the given item. If the item appears in the list after the current position, then the next call to GetNext( ) returns the item. If the item does not appear, then GetNext( ) returns nothing.


AcIterator::SkipTo method

Skips to the given numbered location in the list.

Syntax

Sub SkipTo( position As Integer )

Description

Moves the iterator to the given numbered location in a list. If the position specified is greater than the number of items in the list, the iterator is set to the end of the list. If the position is a negative number, the iterator is set to the beginning of the list.


Class AcLabelControl

A class you use in the report design to display static, nonsearchable text labels.

Description

A label control is a constant control that is fully defined at design time. Use it to display titles and textual information that do not come from a data row. You specify the text to display through the Text property. To display string data from a data row, use AcTextControl instead.

Although the properties of a label control are typically set in the Design Editor, you can write code to change its attributes at run time when the Factory builds it. For example, you could change the color or text of the label depending on the value of another control. To accomplish this task, you can override the label control's Build( ) or BuildFromRow( ) method. The Build method you override depends on whether the label control is contained in a frame that processes data rows or not. For more information about when Build( ) and BuildFromRow( ) are called, see AcBaseFrame::Build method and AcDataFrame::BuildFromRow method.

Variables

Variable	Type	Description
BackgroundIsClear	Boolean	A flag that indicates whether the background is transparent.
BackgroundColor	AcColor	Determines the background color.
Border	AcLineStyle	Determines the border, if any, to place around the control.
Font	AcFont	Determines the font to use for text in the control.
Text	String	Contains the text of the control.
TextPlacement	AcTextPlacement	Determines where to place the text in the control.
Properties

Property	Type	Description
BackgroundIsClear	Boolean	A flag that indicates whether the background is transparent.
BackgroundColor	AcColor	Determines the background color.
Border	AcLineStyle	Determines the border, if any, to place around the control.
Font	AcFont	Determines the font to use for text in the control.
Text	String	Contains the text of the control.
TextPlacement	AcTextPlacement	Determines where to place the text in the control.


Class AcLeftRightPageList

Methods

Builds a page list with alternating left-right pages.

Description

The AcLeftRightPageList class provides a report format that has alternating left and right pages. AcLeftRightPageList has two component relationships: LeftPage and RightPage. It also has a FirstIsRight property that can be set in the property sheet of the Design Editor.

When set to True, AcLeftRightPageList starts the first page as a right-hand page. When set to False, AcLeftRightPageList starts the first page as a left-hand page.

Properties

Property	Type	Description
FirstIsLeft	Boolean	True if the first page in the page list is a left-hand page.
LeftPage	AcPage	The page style to use for left-hand pages.
RightPage	AcPage	The page style to use for right-hand pages.
Methods

Method	Type	Description
NewLeftPage( )	AcPage	Instantiates the left page.
NewRightPage( )	AcPage	Instantiates the right page.


Methods for class AcLeftRightPageList

AcLeftRightPageList::NewLeftPage method

AcLeftRightPageList::NewRightPage method


AcLeftRightPageList::NewLeftPage method

Instantiates the left page.

Syntax

Function NewLeftPage( ) As AcPage

Description

This method is automatically generated by the Design Editor. Override this method if you want to perform custom processing for new left pages.

Return value

The new page.


AcLeftRightPageList::NewRightPage method

Instantiates the right page.

Syntax

Function NewLeftPage( ) As AcPage

Description

This method is automatically generated by the Design Editor. Override this method if you want to perform custom processing for new right pages.

Return value

The new page.


Class AcLinearFlow

Methods

An abstract base class that provides logic for adding frames to a flow that fills in one direction, either top-down or left-to-right.

Description

AcLinearFlow is the abstract base class for flows that fill in one direction, either top-down or left-to-right. Top-down flows fill with frames in the standard top-down order, as described in Class AcTopDownFlow. The left-to-right flow fills with frames starting on the left-hand side of the flow, with each subsequent frame placed just to the right of the previous frame. When the framework receives a frame that does not fit in the remaining space in the flow, the framework advances to the next flow or page.

If you want to ensure that a flow is just large enough to hold its frames, with no wasted space, set the ShrinkToFit property to True.

Variables

Variable	Type	Description
Alignment	AcFlowPlacement	Specifies whether the frames are to appear left justified, centered, or right justified within the flow.
Margins	AcMargins	Space to allow between the border and the contained frames.
ShrinkToFit	Boolean	Set to True to make the flow just large enough to hold the frames that it contains. False is the default.
Properties

Property	Type	Description
Alignment	AcFlowPlacement	Specifies whether the frames are to appear left justified, centered, or right justified within the flow.
Margins	AcMargins	Space to allow between the border and the contained frames.
ShrinkToFit	Boolean	Makes the flow just large enough to hold the frames that it contains.
Methods

Method	Type	Description
AddFrame( )	Boolean	Adds the frame to the flow.
AdjustFooter( )	N/A	Adjusts resizable page footers to align at the bottom of the page.
GetInsideOrigin( )	AcPoint	Returns the top of the content rectangle of the flow after allowing for margins.
GetInsideRect( )	AcRectangle	Returns the size and position of the content rectangle of the flow after allowing for margins.
GetInsideSize( )	AcSize	Returns the size of the content rectangle of the flow after allowing for margins.


Methods for class AcLinearFlow

AcLinearFlow::AddFrame method

AcLinearFlow::AdjustFooter method

AcLinearFlow::GetInsideOrigin method

AcLinearFlow::GetInsideRect method

AcLinearFlow::GetInsideSize method


AcLinearFlow::AddFrame method

See also

Adds the frame to the flow.

Syntax

Function AddFrame( frame As AcFrame ) As Boolean

frame

The frame to add to the book.

Description

The AddFrame( ) method adds the frame to the flow. If there is enough space in the flow to contain the frame, it is added to the flow and the amount of available space in the flow is adjusted accordingly. If there is not enough space, AddFrame creates a new page and adds the frame to the top of the new flow on the new page.

The frame is put in the flow based on its Alignment property set in the Content Editor.


See also

AcFlow::AddFrame method

AcPageList::AddFrame method


AcLinearFlow::AdjustFooter method

See also

Adjusts the position of a resizable footer to align it at the bottom of the page.

Syntax

Sub AdjustFooter ( Footer As AcFrame )

Description

AdjustFooter( ) aligns resizable footers to the bottom of the page. This allows reports to have text controls in PageFooter slots that vary in size, yet align properly on the page. To change the size of a page footer, create the page footer at its largest possible size, then shrink it to the desired size later.

If you implement a custom flow, override this method to handle footer alignment.

This method is similar to the AcFlow::ShiftFooterUp( ) method.


See also

AcFlow::ShiftFooterUp method


AcLinearFlow::GetInsideOrigin method

See also

Returns the upper left corner of the content rectangle.

Syntax

Function GetInsideOrigin( ) As AcPoint

Description

Returns the upper left corner of the content rectangle of the flow, after allowing for margins.


See also

AcTopDownFlow::GetInsideRect method

AcTopDownFlow::GetInsideSize method


AcLinearFlow::GetInsideRect method

See also

Returns the size and position of the content rectangle.

Syntax

Function GetInsideRect( ) As AcRectangle

Description

Returns the size and position of the content rectangle within the flow, after allowing for margins.


See also

AcTopDownFlow::GetInsideOrigin method

AcTopDownFlow::GetInsideSize method


AcLinearFlow::GetInsideSize method

See also

Returns the size of the content rectangle.

Syntax

Function GetInsideSize( ) As AcSize

Description

Returns the size of the content rectangle, after allowing for margins.


See also

AcTopDownFlow::GetInsideOrigin method

AcTopDownFlow::GetInsideRect method


Class AcLineControl

A class you use in the report design to display a line.

Description

A line control is a constant control that is fully defined at design time. The properties you are likely to set are Position, EndPosition, and LineStyle. Position specifies the starting coordinates of the line, and EndPosition, the end coordinates. The X-coordinate is measured from the top left corner of the frame that contains the line control. The Y-coordinate is measured from the top of the enclosing frame.

The Line Style properties let you specify the color, style, and width of the line. Because the length of the line is determined by the Position and EndPosition properties, and the width by the width property under LineStyle, Actuate ignores the Size properties. The Size properties are inherited from AcVisualComponent.

Variables

Variable	Type	Description
EndPosition	AcPoint	The endpoint of the line, relative to the top left.
LineStyle	AcPoint	The style of the line.
Properties

Property	Type	Description
EndPosition	AcPoint	The endpoint of the line, relative to the top left.
LineStyle	AcPoint	The style of the line.
Considerations for HTML reports

HTML provides only horizontal lines.  HTML calls these lines "rules."  If you include a horizontal line in a frame in an HTML report, AFC represents this line as an HTML rule.  If the line is vertical, or at an angle, AFC ignores the line control when generating the HTML output. AFC uses the Position.Y and EndPosition.Y properties to determine if the line is horizontal.  AFC considers the line to be horizontal if these two properties have the same value.

HTML requires that horizontal rules appear on a line by themselves.  If you include a line control in a frame on the same line as text, AFC will place text before the line on one line, the rule on a second line, and text after the rule on a third line.

Use AcHtmlRuleControl to include a horizontal line in an HTML report. AcHtmlRuleControl provides additional properties specifically for HTML rules.


Class AcList

Example   See also   Methods

A base class that defines the list interface.

Description

The AcList class is an abstract class that defines the list interface. It provides a complete set of list operations including the ability to add an item anywhere in the list, to remove and item anywhere in the list, or to obtain statistics about the contents of the list.

Actuate defines one concrete subclass of AcList, AcSingleList, which implements a singly linked list.

Methods

Method	Type	Description
AddToHead( )	N/A	Adds an item to the beginning of a list.
Contains( )	Boolean	Returns True if the list contains the item.
Copy( )	N/A	Copies the contents from another list to the end of this list.
GetIndex( )	Integer	Returns the position of the node specified in the list.
InsertAfter( )	N/A	Inserts a node in the list after the node specified.
InsertBefore( )	N/A	Inserts a node in the list before the node specified.
RemoveHead( )	AnyClass	Removes the first node from the list.


Example

The following example shows how you create a list and traverse it with a list iterator.

Class MyClass

Dim counter As Integer

End Class

Sub Main ( )

Dim list As AcList

Dim obj As MyClass

Dim count As Integer

Dim iterator As AcIterator

'Create a list

Set list = New AcSingleList

'Create an object and add it to the list

Set obj = New MyClass

obj.counter = 1

list.AddToTail( obj )

'Create a second object and append it to the list

Set obj = New MyClass

obj.counter = 2

list.AddToTail( obj )

'Count the number of objects in the list

count = list.GetCount( )

MsgBox "Number of objects in the list: " & count

'Create a list iterator and get each object in the list

Set iterator = New AcSingleListIterator( list )

Do While iterator.HasMore( )

Set obj = iterator.GetNext( )

MsgBox "The position of this object in the list:" & obj.counter

Loop

'Delete the objects from the list

list.RemoveHead( )

list.RemoveHead( )

End Sub


See also

Class AcCollection

Class AcOrderedCollection

Class AcSingleList


Methods for class AcList

AcList::AddToHead method

AcList::Contains method

AcList::Copy method

AcList::GetIndex method

AcList::InsertAfter method

AcList::InsertBefore method

AcList::RemoveHead method


AcList::AddToHead method

Adds an item to the beginning of the list.

Syntax

Sub AddToHead( item As AnyClass )

item

The node to add to the list.

Description

Adds the item specified to the beginning of the list.


AcList::Contains method

Determines whether the list contains the item.

Syntax

Function Contains( item As AnyClass ) As Boolean

item

The list item.

Description

This method determines whether a list contains the item specified. It searches the list for the first occurrence of the item.

Return value

True if the list contains the specified item.

False if the list does not contain the specified item.


AcList::Copy method

Copies the contents from another list to the end of this list.

Syntax

Sub Copy ( from As AcList )

from

The list from which to copy items.

Description

The Copy( ) method copies into the current list the contents of another list. Copy( ) appends the contents to the end of the list. Copy( ) does not change the content of the other list, the items are now in both lists.


AcList::GetIndex method

Returns the position of the node specified.

Syntax

Function GetIndex( item As AnyClass ) As Integer

item

The node to locate in the list.

Description

This method gets the index of the item specified from the list.

Return value

The position of the specified node in the list.

Zero if the node does not exist in the list.


AcList::InsertAfter method

Inserts an item following a specified node.

Syntax

Sub InsertAfter( item As AnyClass, after As AnyClass )

item

The item to insert into the list.

after

The item after which to insert the specified item.

Description

Inserts a node following the specified node . If the specified item node cannot be located, InsertAfter( ) raises an error.


AcList::InsertBefore method

Inserts an item before the specified node.

Syntax

Sub InsertBefore( item As AnyClass, before As AnyClass )

item

The item to insert into the list.

before

The item before which to insert the item specified.

Description

Inserts a node before the specified node. If the specified item node cannot be located, InsertBefore( ) raises an error.


AcList::RemoveHead method

Removes the first node from a list.

Syntax

Function RemoveHead( ) As AnyClass

Description

Removes and returns the first node from a list.

Return value

Returns the class of the new head node after the original head node is removed.


Class AcMemoryBuffer

See also   Methods

A data filter that converts a sequential data stream into one which allows random access by buffering data rows in memory.

Description

Many data sources provide only the ability to read rows in a sequential first-to-last order. However, there are times when you need to move through the data in random order, perhaps making multiple passes over certain groups of data to print the data first in a graph, then in a tabular format. The AcMemoryBuffer class acts as a converter to change a sequential data source into a random-access data stream. It does so by storing (buffering) data rows in memory as you read them so that you can return back to them again later. You don't need to use this class if your data source already provides random access.

Because this data filter supports random access, the CanSeek( ) method returns True, and all the various random-access methods such as SeekTo( ) and Rewind( ) are available.

AcMemoryBuffer lets you manipulate data as if you had direct access to the input source. You can locate rows by specifying a row number with SeekTo( ) or by specifying a relative position with SeekBy( ). You can rewind to the beginning of the data buffer with Rewind( ) or advance to the end with SeekToEnd( ). The row number starts at 1. (See AcDataAdapter for details.)

Although not required, you may choose to flush the buffer occasionally to remove from memory those rows that you no longer need. For example, if you need to make two passes over the data for each customer, you can flush the rows for each customer as you complete the process. Flushing the buffer causes no change to the way you access rows; you just won't be able to seek back to revisit the flushed rows. See the FlushBuffer( ) and FlushBufferTo( ) methods for details.

You can also use the memory buffer class to gather data rows that your application creates programmatically. For example, you might want to produce a report of account activity. For every account with exceptional items, you want to create a second data row that you will print in a second report. To do this, create a memory buffer without an input adapter, then call AddRowToBuffer( ) to add each of your exception rows to the buffer. Then, in a later report section, you can read and process these rows in the usual way.

Methods

Method	Type	Description
AddRowToBuffer( )	N/A	Programmatically adds a row to the data row buffer.
FlushBuffer( )	N/A	Frees the rows currently buffered.
FlushBufferTo( )	N/A	Frees the rows in the buffer up to and including a specific row.
GetBufferCount( )	Integer	Gets the number of rows currently in the buffer.
GetBufferStart( )	Integer	Gets the position (relative to the beginning of the input set) of the first row in the buffer. The first row is 1.


See also

Class AcDataAdapter

Class AcDataSource

Class AcMemoryDataSorter

Class AcSingleInputFilter


Methods for class AcMemoryBuffer

AcMemoryBuffer::AddRowToBuffer method

AcMemoryBuffer::FlushBuffer method

AcMemoryBuffer::FlushBufferTo method

AcMemoryBuffer::GetBufferCount method

AcMemoryBuffer::GetBufferStart method


AcMemoryBuffer::AddRowToBuffer method

Adds a row to the data row buffer.

Syntax

Sub AddRowToBuffer( row As AcDataRow )

row

The data row to add to the buffer.

Description

AddRowToBuffer( ) adds the specified row to the end of the buffer. Use this method to programmatically add a row to the buffer. This method does not modify the current read position.


AcMemoryBuffer::FlushBuffer method

See also

Frees the rows currently buffered.

Syntax

Sub FlushBuffer( )

Description

FlushBuffer( ) removes the current set of rows from the buffer. You may choose to flush the buffer occasionally to remove from memory those rows that you no longer need.

Flushing the buffer causes no change to the way you access rows; you just won't be able to seek back to revisit the flushed rows. For example, if the buffer currently contains rows 20 through 40, and you flush the buffer, you can still seek to row 41, 42, or any number up to the number of rows in the input set. However, if you try to seek back to row 40 or earlier, you will get a Basic runtime error.


See also

AcDataAdapter::FlushBuffer method

AcDataAdapter::FlushBufferTo method

AcMemoryBuffer::FlushBufferTo method


AcMemoryBuffer::FlushBufferTo method

See also

Frees the rows in the buffer up to and including a specific row.

Syntax

Sub FlushBufferTo( posn As Integer )

posn

The data row to flush to.

Description

FlushBufferTo( ) lets you flush rows in the buffer up to and including the row at the given position. For example, when processing rows programmatically, you may read rows from one customer until you reach the first row for the next customer. After you are done processing the rows for the first customer, you can flush those rows, but retain the first row for the next customer.

This method does nothing if the given position is before the first buffered row or after the last buffered row. If the position is the same as the last row in the buffer, then this method does the same thing as FlushBuffer( ).


See also

AcDataAdapter::FlushBuffer method

AcDataAdapter::FlushBufferTo method

AcMemoryBuffer::FlushBuffer method


AcMemoryBuffer::GetBufferCount method

Gets the number of rows currently in the buffer.

Syntax

Function GetBufferCount( ) As Integer

Description

This method determines the number of rows that are currently in the buffer. Rows that have been flushed are not counted.

Return value

The number of rows currently in the buffer.


AcMemoryBuffer::GetBufferStart method

Gets the position of the first row in the buffer.

Syntax

Function GetBufferStart( ) As Integer

Description

If the buffer has data rows, this method returns the position of the first row, relative to the beginning of the input set. If the buffer is empty, then this function returns the position of the row that will become the first row in the buffer the next time you call Fetch( ).

Return value

Returns the position, relative to the beginning of the input set, of the first row in the buffer.


Class AcMemoryDataSorter

See also   Methods

A data filter that has the capability to sort rows in a memory buffer.

Description

AcMemoryDataSorter is a data filter that uses the buffering capabilities of its superclass, AcMemoryBuffer, to read and store data rows in memory. In addition, it provides a sort algorithm that subclasses can refine to implement the sort details.

Subclassing AcMemoryDataSorter

Create a subclass from AcMemoryDataSorter to implement the sort functions to process data row by

1	Deriving a class from AcMemoryDataSorter.

2	Overriding the Compare( ) method, which implements the sort algorithm.

Methods

Method	Type	Description
Compare( )	Integer	A pure virtual method that must be overridden to implement the comparison logic.
CompareKeys( )	Integer	Compares two strings or numbers.


See also

Class AcDataAdapter

Class AcDataSource

Class AcMemoryBuffer

Class AcSingleInputFilter


Methods for class AcMemoryDataSorter

AcMemoryDataSorter::Compare method

AcMemoryDataSorter::CompareKeys method


AcMemoryDataSorter::Compare method

Example   See also

Compares two data rows.

Syntax

Function Compare( row1 As AcDataRow, row2 As AcDataRow ) As Integer

row1

A reference to the first row to compare.

row2

A reference to the second row to compare.

Description

This method defines how the sort algorithm determines when one row is considered smaller than another. Your comparison is based on sort keys. A sort key is a column on which you want to base the sort. The following example shows a sort based on State and Customer Name.

When writing the Compare method, cascade the comparisons as follows:

•	If the first sort key column differs between the two rows, return 1 if
key 1 > key 2 or -1 if key 1 < key 2.

•	If the first sort key columns are the same, then repeat the process on the second key, third key, and so on.

This process does not work, however, for real numbers because of the rounding errors that can be introduced when converting from a floating point to an integer.

You must override the Compare( ) method when you create a custom sort filter. If you forget to override this method, you will get a runtime error when the memory sorter attempts to sort the data.

Return value

A positive number if row1 goes after row2.

0 if row1 equals row2.

A negative number if row1 goes before row2.


Example

The following example compares two customers by state. If the states are identical, then Compare( ) compares the customer names.

Function Compare( row1 As AcDataRow, row2 As AcDataRow ) As Integer

Dim Cust1 As CustomerRow

Dim Cust2 As CustomerRow

Set Cust1 = row1

Set Cust2 = row2

Compare = CompareKeys( Cust1.State, Cust2.State )

If Compare = 0 Then

Compare = Cust1.CustName - Cust2.CustName

End If

End Function


See also

AcMemoryDataSorter::CompareKeys method


AcMemoryDataSorter::CompareKeys method

See also

Compares two sort keys.

Syntax

Function CompareKeys( key1 As Variant, key2 As Variant ) As Integer

key1

A reference to the first key to compare.

key2

A reference to the second key to compare.

Description

Call CompareKeys( ) to compare two key values in a column. You typically call CompareKeys( ) from Compare( ), which defines the sort algorithm. For an example of using CompareKeys( ), see the example in AcMemoryDataSorter::Compare method.

Return value

-1 if key1 is less than key2.

0 if key1 equals key2.

1 if key1 is more than key2.


See also

AcMemoryDataSorter::Compare method


Class AcMSSQLConnection

Establishes a connection to a Microsoft SQL database.

Description

Use the AcMSSQLConnection class to establish a connection to a Microsoft SQL database. The application must set the server name, user name, and password prior to connecting. Once connected, the application should not change these values.

Variables

Variable	Type	Description
DllPath	String	The name of the DLL providing client database.
Password	String	The client password for the connection.
ServerName	String	The client server name for the connection.
UserName	String	The client user name for the connection.
Properties

Property	Type	Description
DllPath	String Variable	The name of the DLL providing client database. Default is the most common name used for the connectivity DLL provided by Microsoft.
Password	String Variable	The client password for the connection.
ServerName	String Variable	The client server name for the connection.
UserName	String Variable	The client user name for the connection.


Class AcMultipleInputFilter

Example   See also   Methods

A base class for data filters--one type of data adapter--that accepts input from any number of data adapters, processes the data, and then passes it to the next data adapter or to the report.

Description

AcMultipleInputFilter defines the mechanism for filtering and sorting data from multiple data sources. Multi-input data filters work with data sources to produce and deliver data rows to the report, as the following figure illustrates.

The data sources are not limited to retrieving data from a single input source, as the figure suggests. For example, one data source could be getting data from an SQL database, and another from an ODBC database.

A multi-input data filter receives input from other data adapters, either data sources or other data filters. You can use the Design Editor to specify the input adapters that provide input rows to the filter.

To implement the filter algorithm, you need to override the Fetch( ) method.

Working with the input adapters

The multiple input filter creates, opens, reads, and closes a set of one or more input adapters. You specify these adapters by dropping them into the Input slot in the structure pane. The multiple input filter automatically instantiates, opens, and closes the adapters. You must write code in the Fetch( ) method to work with the input adapters.

The Start( ) method of the multiple input filter instantiates each of the input adapters that you specify in the Input slot in the structure pane. These adapters live in an AcList called InputAdapters. Instead of (or in addition to) the adapters you specify in the structure pane, you can also add adapters programmatically by using the various methods on AcList. Start( ) then iterates over these to give each adapter its connection and starts the adapter. Similarly, Finish( ) iterates over each adapter to close the input adapter.

You must implement the Fetch( ) method to work with the adapters. When you do, you can use the various list methods on AcList to work with the list of adapters. Also, you can use an iterator (of type AcIterator) to easily loop over the adapters. The adapters appear in the list in the same order that they appeared in the structure pane.

You can build many kinds of filters using this class. For example, you can create a subclass to

•	Concatenate together the rows from each of the input filters. This is a union filter.

•	Join or merge rows from one input adapter with those from a second input adapter. This is a merge filter.

•	Return all rows from one adapter, except those that appear in another adapter. This is a subtraction filter.


Example

The following example overrides Start( ), Fetch( ), and Finish( ) to create a union filter. It also defines two variables. The first is called UnionIter of type AcIterator. The second is called CurrentInput of type AcDataAdapter.

Function Start( ) As Boolean

' Start the multiple input filter

Start = Super::Start( )

If Not Start Then

Exit Function

End If

' Keep track of the input adapter from which to read.

Set UnionIter = InputAdapters.NewIterator( )

Set CurrentInput = UnionIter.GetNext( )

End Function

Function Fetch( ) As AcDataRow

Do While True

' If all the adapters have been read, then just return Nothing.

If CurrentInput Is Nothing Then

Exit Function

End If

' Try to read the next row from the current input adapter.

Set Fetch = CurrentInput.Fetch( )

' If there is a row available, then return it.

If Not Fetch Is Nothing Then

Exit Function

End If

' Move to the next input adapter.

Set CurrentInput = UnionIter.GetNext( )

Loop

End Function

Sub Finish( )

' Delete the iterator created earlier

Set UnionIter = Nothing

' Finish the multiple input filter.

Super::Finish( )

End Sub

Subclassing AcMultipleInputFilter

Typically, you subclass AcMultipleInputFilter to create a custom filter.

How to derive from AcMultipleInputFilter

Derive a subclass from AcMultipleInputFilter by

1	Optionally overriding Start( ) to specify a different way to create the input adapters.

2	Overriding Fetch( ) to specify how to process the data.

Variables

Variable	Type	Description
InputAdapters	AcList	A list of the input adapters.
Methods

Method	Type	Description
NewInputAdapters( )	AcDataAdapter	Instantiates the input adapters specified in the Input slot.


See also

Class AcDataAdapter

Class AcSingleInputFilter


Methods for class AcMultipleInputFilter

AcMultipleInputFilter::NewInputAdapters method


AcMultipleInputFilter::NewInputAdapters method

Creates the input adapters.

Syntax

Sub NewInputAdapters( )

Description

Start( ) calls NewInputAdapters( ) to create the input adapters. You do not need to override this method unless you want to specify a different way to create the input adapters.

By default, this method instantiates the adapters you dropped into the Input slot in the structure pane.


Class AcObjectArray

See also   Methods

A dynamic array of objects.

Description

Use AcObjectArray to create a resizable array of objects. AcObjectArray provides the mechanism for resizing an array as needed. The object array can be more efficient than an AcSingleList collection if your application traverses the objects in the collection frequently.

Array indexes start at 1 and end at the GetCount( ) value. If you try to retrieve a value beyond the bounds of an array using GetAt( ), Actuate returns a run-time error. You can, however, use SetAt( ) to set the value of an array beyond its current upper bound. SetAt( ) resizes the array as needed.

To reduce memory allocations, the array expands its internal storage in predefined increments. By default, the increment value is 10. Whenever the object array needs to expand, the framework allocates 10 slots. If you expect your array to grow in larger amounts, you can use SetGrowthIncrement( ) to increase the increment value.

Methods

Method	Type	Description
AddToTail( )	N/A	Adds an item to the end of the array.
GetAt( )	AnyClass	Returns the item at the specified  location in the index.
GetCount( )	Integer	Returns the number of items in the array.
GetTail( )	AnyClass	Returns the last item in the array.
IsEmpty( )	Boolean	Returns whether the array is empty or not.
New( )	N/A	Constructor.
NewIterator( )	AcIterator	Creates an iterator for the array.
Remove( )	N/A	Removes a specified item from the array.
RemoveAll( )	N/A	Removes all items from the array.
RemoveTail( )	AnyClass	Removes the last item in the array.
ResizeBy( )	N/A	Increase or decrease the size of the  array by a specified amount.
ResizeTo( )	N/A	Sets the size of the array.
SetAt( )	N/A	Places an object in a specified array  location.
SetGrowth Increment( )	N/A	Sets the number of slots to add to the  array each time it expands.


See also

Class AcIterator

Class AcOrderedCollection


Methods for class AcObjectArray

AcObjectArray::AddToTail method

AcObjectArray::GetAt method

AcObjectArray::GetCount method

AcObjectArray::GetTail method

AcObjectArray::IsEmpty method

AcObjectArray::New method

AcObjectArray::NewIterator method

AcObjectArray::Remove method

AcObjectArray::RemoveAll method

AcObjectArray::RemoveTail method

AcObjectArray::ResizeBy method

AcObjectArray::SetAt method

AcObjectArray::SetGrowthIncrement method


AcObjectArray::AddToTail method

See also

Adds an item to the end of the array.

Syntax

Sub AddToTail( obj As AnyClass )

obj

The object to add to the end of the array.

Description

Use AddToTail( ) to add an object to the end of an array. The size of the array increases by one. To add an object in any other location of the array, use SetAt( ).


See also

AcObjectArray::SetAt method


AcObjectArray::GetAt method

See also

Returns the item at the specified location in the index.

Syntax

Function GetAt( index As Integer ) As AnyClass

index

The position of the object to retrieve. The index must be from 1 to the current size of the array.

Description

Use GetAt( ) to retrieve an object from the specified location in the array. If you specify an invalid index, Actuate returns a run-time error.

Return value

A reference to the retrieved object.


See also

AcObjectArray::GetTail method


AcObjectArray::GetCount method

Returns the number of items in the array.

Syntax

Function GetCount( ) As Integer

Description

Use GetCount( ) to determine the number of items in an array. GetCount( ) returns the upper bound of the array. Some of the array locations might not contain objects. Empty array locations are set to Nothing.

GetCount( ) does not return the actual size of the internal array, which can be larger than the current logical upper bound of the array. When you add an item to the array using SetAt( ) or AddToTail( ), or remove an item using RemoveTail( ) or Remove( ), Actuate adjusts the array count automatically.

Return value

The number of items in an array.


AcObjectArray::GetTail method

See also

Returns the last item in the array.

Syntax

Function GetTail( ) As AnyClass

Description

Use GetTail( ) to retrieve the last object in the array. To get an object in any other location in the array, use GetAt( ).

Return value

A reference to the last object in the array.


See also

AcObjectArray::GetAt method


AcObjectArray::IsEmpty method

Returns whether the array is empty or not.

Syntax

Function IsEmpty( ) As Boolean

Description

Use IsEmpty( ) to check if an array contains any objects.

Return value

True if there are no items in the array.


AcObjectArray::New method

Constructor.

Syntax

Sub New( )

Description

New( ) initializes the array object. It sets the initial growth increment to 10.


AcObjectArray::NewIterator method

See also

Creates an iterator for the array.

Syntax

Function NewIterator( ) As AcIterator

Description

Use NewIterator( ) to create an iterator over the array. With the iterator, you can access the items in an array the same way you access items in a list. An alternative to using an iterator is to use a For loop and the GetAt( ) method.

Return value

A reference to the iterator.


See also

AcObjectArray::GetAt method


AcObjectArray::Remove method

See also

Removes a specified item from the array.

Syntax

Sub Remove( item As AnyClass )

item

The object to delete.

Description

Use Remove( ) to delete a specific object from an array. Remove( ) shrinks the array by one. If you specify an object that is not in the array, Remove( ) does nothing. To remove all objects in an array, use RemoveAll( ).

Actuate automatically deletes objects if they are transient and their reference count goes to zero.


See also

AcObjectArray::RemoveAll method

AcObjectArray::RemoveTail method


AcObjectArray::RemoveAll method

See also

Removes all items from the array.

Syntax

Sub RemoveAll( )

Description

Use RemoveAll( ) to delete all objects from an array. To remove a single object from an array, use Remove( ).

Actuate automatically deletes objects if they are transient and their reference count goes to zero.


See also

AcObjectArray::Remove method

AcObjectArray::RemoveTail method


AcObjectArray::RemoveTail method

See also

Removes the last item in the array.

Syntax

Function RemoveTail( ) As AnyClass

Description

Use RemoveTail( ) to delete the last object in an array. To delete an object in any other location in the array, use Remove( ).

Return value

A reference to the deleted object.


See also

AcObjectArray::Remove method

AcObjectArray::RemoveAll method


AcObjectArray::ResizeBy method

See also

Increase or decrease the size of the array by a specified amount.

Syntax

Sub ResizeBy( delta As Integer )

delta

The amount by which to increase or decrease the array size. A positive number increases the size. A negative number decreases the size.

Description

Use ResizeBy( ) to change the size of the array by a specified amount. If you expand the array, the new array locations at added to the end of the array and are set to Nothing. To place objects in the array locations, you can use SetAt( ) or AddToTail( ).

If you want to set the array to a specific size, use ResizeTo( ).


See also

AcObjectArray::AddToTail method

AcObjectArray::ResizeTo method

AcObjectArray::SetAt method


AcObjectArray::ResizeTo method

See also

Sets the size of the array.

Syntax

Sub ResizeTo( newSize As Integer )

newSize

The new size of the array.

Description

Use ResizeTo( ) to change the size of the array. You typically do not need to explicitly resize the array because the array methods do so automatically. For example, when you use SetAt( ) to place an object in an array location and you specify a location beyond the current size, SetAt( ) automatically resizes the array.

If you want to increase or decrease the array size by a specific amount, use ResizeBy( ).


See also

AcObjectArray::ResizeBy method

AcObjectArray::SetAt method


AcObjectArray::SetAt method

See also

Places an object in a specified array location.

Syntax

Sub SetAt( index As Integer, obj As AnyClass )

index

The location in which to store the object. The index must be 1 or greater.

obj

The object to store.

Description

Use SetAt( ) to store an object in a particular array location. If the index you specify is beyond the current array size, SetAt( ) resizes the array accordingly. If the index you specify is within the current array size, SetAt( ) places the specified object in the existing location, replacing any object that might be stored there.

To store an object to the end of the array, use AddToTail( ).


See also

AcObjectArray::AddToTail method


AcObjectArray::SetGrowthIncrement method

Sets the number of slots to add to the array each time it expands.

Syntax

Sub SetGrowthIncrement( incr As Integer )

incr

The number of slots to add to the array whenever the array expands.

Description

By default, the array expands its internal storage by 10 whenever the array grows. Use SetGrowthIncrement( ) to increase the default increment value if you expect your array to expand in larger amounts.


Class AcODBCConnection

Establishes a connection to an ODBC database

Description

Use the AcODBCConnection class to establish a connection to an ODBC database. The application must set the connection string, data source, user name, and password prior to connecting. Once connected, the application should not change these values.

Variables

Variable	Type	Description
ConnectionString	String	Any additional text that ODBC needs to establish its connection.
DataSource	String	The ODBC data source.
DllPath	String	The name of the DLL providing client database.
Password	String	The client password for the connection.
UserName	String	The client user name for the connection.
Properties

Property	Type	Description
ConnectionString	String Variable	Any additional text that ODBC needs to establish its connection.
DataSource	String Variable	The ODBC data source.
DllPath	String	The name of the DLL providing client database. Default is the most common name used for the connectivity DLL provided by ODBC.
Password	String Variable	The client password for the connection.
UserName	String Variable	The client user name for the connection.


Class AcOleContainerControl

Methods

Implements an OLE container control.

Description

An AcOleContainerControl holds either an OLE client item or an OCX (OLE custom control). The term OLE container item is a general term for both. AcOleContainerControl contains methods to execute actions for the specific container as well as housekeeping methods. This control does not "own" a client item, but it is associated with one. This class uses the inherited properties ContextID and ContainerID (from AcOleControl) to find the associated OLE container item.

The OLE container item is associated with an OLE data object. You can manipulate the OLE object using OLE Automation. The method Object( ) references the OLE object.

Methods

Method	Type	Description
CloseOrDeactivate( )	Boolean	Closes or deactivates the specified OLE container item.
DoVerb( )	Boolean	Executes the action specified for the specified OLE container item.
Object( )	Object	Returns the OLE object associated with the control.
OnActivate( )	N/A	Called before the container control is displayed.
OnCreate( )	N/A	Called by the framework as the control is created.
OnLButtonDblClk( )	Boolean	Overrides the default implementation in AcVisualComponent.


Methods for class AcOleContainerControl

AcOleContainerControl::CloseOrDeactivate method

AcOleContainerControl::DoVerb method

AcOleContainerControl::Object method

AcOleContainerControl::OnActivate method

AcOleContainerControl::OnCreate method

AcOleContainerControl::OnLButtonDblClk method


AcOleContainerControl::CloseOrDeactivate method

Closes or deactivates the specified OLE container.

Syntax

CloseOrDeactivate( ) As Boolean

Description

Closes or deactivates the specified OLE container. If the OLE container item is in-place and active, CloseOrDeactivate( ) deactivates the container. If the OLE container item is open within the server application, CloseOrDeactivate( ) closes the server application.

Return value

True if the OLE container was closed properly.

False if the item was neither open nor in-place and active.


AcOleContainerControl::DoVerb method

Executes the action specified for the OLE container.

Syntax

Function DoVerb( verb As Integer, view As AcReportView ) As Boolean

verb

The action to take.

view

The view that contains the OLE container.

Description

Finds the associated container item and executes the verb specified. The possible verbs are:

Verb	Description
OleverbPrimary	Primary verb for the container.
OleverbShow	Display container for editing.
OleverbOpen	Edit in server application or in a separate window.
OleverbHide	Hide the OLE container item.
Return value

True if the action specified was executed properly.

False if the action specified was not executed.


AcOleContainerControl::Object method

Returns the OLE data object associated with the OLE container item.

Syntax

Function Object( ) As Object

Description

Finds the associated OLE container item and returns its OLE object as an Object data type. Use the returned object to manipulate the data object using OLE Automation.

Return value

The OLE object associated with the OLE container item.


AcOleContainerControl::OnActivate method

Called by the framework as the control is opened.

Syntax

Sub OnActivate( )

Description

Called by the framework as the control is opened for display in the report. This is different from activating the OLE container item using DoVerb( ). Override this method in a subclass to manipulate the container item before it is displayed.

The default implementation creates a copy if CreateClone is True and updates the key values to identify the newly created clone.


AcOleContainerControl::OnCreate method

Called by the framework as the control is being created.

Syntax

Sub OnCreate( )

Description

Called by the framework as the control is being created. You can override this method to perform custom initialization. The default implementation saves the original container keys if CreateClone is True.


AcOleContainerControl::OnLButtonDblClk method

See also

Overrides the default implementation in AcVisualComponent.

Syntax

Function OnLButtonDblClk( view As AcReportView, shift As AcShiftKeyState, x As Integer, y As Integer ) As Boolean

view

The window the report is in.

Shift

A bit field that indicates if the Shift, Ctrl, or Alt keys were pressed at the time of the event. Shift can contain one of the following values:

Keys pressed	Bit value	Shift value
None	0	NoKeys
Shift	1	ShiftKey
Ctrl	2	ControlKey
Shift + Ctrl	3	Both ShiftKey and ControlKey
Alt	4	AltKey
Shift + Alt	5	Both ShiftKey and AltKey
Ctrl + Alt	6	Both CtrlKey and AltKey
x

The horizontal position of the mouse cursor at the time of the event, measured in pixels relative to the left of the view.

y

The vertical position of the mouse cursor at the time of the event, measured in pixels relative to the top of the view.

Description

OnLButtonDblClk( ) is called by the framework in response to the user double-clicking the OLE container control. This method overrides the default implementation in AcVisualComponent.

The default implementation selects and activates the OLE container using the primary verb. If the user presses the Ctrl key while double clicking, the OLE container item is activated using the Open verb instead.

Return value

True if the event is handled.

False if the event is not handled.


See also

AcVisualComponent::OnLButtonDblClk method

AcOleContainerControl::DoVerb method


Class AcOleControl

Example

An abstract class for OLE controls.

Description

AcOleControl is an abstract class for OLE controls. You normally do not subclass AcOleControl.

Properties

Property	Type	Description
CreateClone	Boolean	True means that the Viewer creates a copy (clone) of the original OLE container item before displaying it; False means that the Viewer displays the original OLE container item.
TrueSize	Boolean	True means to disregard the size of the AFC control. Displays the "true" size of the OLE container item, as reported by the OLE server application. False means to display the OLE container item using the size specified in the AFC control.
TrueSize property

The TrueSize property controls how the control is displayed. TrueSize is most useful for linked OLE items, since the contents and the size can change without using Actuate.

When TrueSize is True, the framework disregards the size of the AFC control. It displays the true size of the OLE container, as reported by the OLE server application. TrueSize is True by default, but the Design Editor automatically changes it if the user changes the size of the AFC OleContainer control. The user can change this setting in the Design Editor.

With TrueSize set to True, the content appears as it was intended by the server application, but you have no control over the size it takes. It may, if the size increased since the design was created, overwrite other elements of the report.

When TrueSize is False, the framework displays the OLE container using the size specified in the AFC. When False, you will always know how much room on the display the control is taking, but the content might appear distorted.

CreateClone property

This setting affects multiple OLE containers. If True, the AFC Basic code creates a copy (clone) of the original OLE container. You can then change the item before it displays. With a clone, the changes only affect this one instance.

If the CreateClone property is False, the change affects all instances. If you don't intend to make changes to each instance, you can set this property to False to reduce memory requirements.


Example

You want to show a graph using OLE, which will appear several times on each page. The graph needs to change, using OLE Automation, depending on the data in the report. Set CreateClone to True; otherwise, changes to one graph will affect all the others.

The code displaying the OLE item removes the clones from memory when done. The setting of CreateClones is used to determine this (see the previous discussion). Thus, it is important that this property correctly reflect the status of the OLE item. Be aware of this when modifying default behaviors.


Class AcOracleConnection

Establishes a connection to an Oracle database.

Description

Use the AcOracleConnection class to establish a connection to an Oracle database. The application must set the server name, user name, and password prior to connecting. Once connected, the application should not change these values.

Variables

Variable	Type	Description
DllPath	String	The name of the DLL providing client database.
Password	String	The client password for the connection.
HostString	String	The client server name for the connection.
UserName	String	The client user name for the connection.
Properties

Property	Type	Description
DllPath	String	The name of the DLL providing client database. Default is the most common name used for the connectivity DLL provided by Oracle.
Password	String Variable	The client password for the connection.
HostString	String Variable	The client server name for the connection.
UserName	String Variable	The client user name for the connection.


Class AcOrderedCollection

See also   Methods

The base class for the Actuate ordered collection classes.

Description

A collection contains objects of any type. An ordered collection enables you to control the order in which objects appear in a collection.

Methods

Method	Type	Description
AddToTail( )	N/A	Adds an item to the end of the collection.
GetAt( )	AnyClass	Returns the item at the specified location  in the collection.
GetHead( )	AnyClass	Returns the first item in the collection.
GetTail( )	AnyClass	Returns the last item in the collection.
RemoveTail( )	AnyClass	Removes the last item in the collection.


See also

Class AcCollection

Class AcIterator


Methods for class AcOrderedCollection

AcOrderedCollection::AddToTail method

AcOrderedCollection::GetAt method

AcOrderedCollection::GetHead method

AcOrderedCollection::GetTail method

AcOrderedCollection::RemoveTail method


AcOrderedCollection::AddToTail method

See also

Adds an item to the end of the collection.

Syntax

Sub AddToTail( item As Anyclass )

item

The object to add to the collection.

Description

Use AddToTail( ) to add an object to the end of a collection. If you create an iterator over the collection immediately after calling AddToTail( ), the object you just added is the last object the iterator returns.


See also

Class AcIterator


AcOrderedCollection::GetAt method

See also

Returns the item at the specified location in the collection.

Syntax

Function GetAt( index As Integer ) As AnyClass

index

The position of the object to retrieve.

Description

Use GetAt( ) to get a reference to the object at the specified location in the collection. If you specify an invalid index, Actuate returns a run-time error.

Return value

A reference to the object at the specified location in the collection.


See also

AcOrderedCollection::GetHead method

AcOrderedCollection::GetTail method


AcOrderedCollection::GetHead method

See also

Returns the first item in the collection.

Syntax

Function GetHead( ) As AnyClass

Description

Use GetHead( ) to get a reference to the first object in the collection. If the collection is empty, Actuate returns a run-time error. Therefore, if you do not know if the collection contains any objects, call IsEmpty( ) first.

Return value

A reference to the first object in the collection.


See also

AcCollection::IsEmpty method

AcOrderedCollection::GetTail method


AcOrderedCollection::GetTail method

See also

Returns the last item in the collection.

Syntax

Function GetTail( ) As AnyClass

Description

Use GetTail( ) to get a reference to the last object in the collection. If the collection is empty, Actuate returns a run-time error. Therefore, if you do not if the collection contains any objects, call IsEmpty( ) first.

Return value

A reference to the last object in the collection.


See also

AcCollection::IsEmpty method

AcOrderedCollection::GetHead method


AcOrderedCollection::RemoveTail method

See also

Removes the last item in the collection.

Syntax

Function RemoveTail( ) As AnyClass

Description

Use RemoveTail( ) to delete the last object in the collection. If the collection is empty, Actuate returns a run-time error. Therefore, if you do not know if the collection contains any objects, call IsEmpty( ) first.

Return value

A reference to the deleted object.


See also

AcCollection::IsEmpty method

AcOrderedCollection::AddToTail method


Class AcPage

Methods

The base class for all pages.

Description

The AcPage class represents pages in your report. When you create the page class, you set the size of the page to the size and orientation you need. The Factory creates pages, one at a time as needed, when building reports. Pages are persistent in the ROI file. The Viewer displays pages as you browse through a report. Pages can contain flows and other page decoration controls. Pages do not work with data rows.

Pages are identified with two numbers. The first is the page index which identifies the position (starting with 1) of the page within the report. The other is the page number, which you can display on the page in the format you desire (such as 3-3, 3-4, 3-5, etc.). You create the formatted page number by setting the PageNumberFormat property or by overriding the FormatPageNumber( ) method.

Factory Protocol

Task	Method
1 Instantiates and starts the contents of the frame.	Start( )
2 Creates the formatted page number.	FormatPageNumber( )
3 Adds each frame to the page.	AddFrame( )
4 Finishes each of the content objects.	Finish( )
Variables

Variable	Type	Description
PageIndex	String	The formatted page number.
PageNumber	Integer	The number of the page within the report, starting with 1.
Properties

Property	Type	Description
PageNumberFormat	String Function	The format string to use when formatting the page number. The format must be compatible with the Format$( ) function.
Methods

Method	Type	Description
FormatPageNumber( )	String	Returns the formatted page number. You can override this method if your formatting requires writing code.
GetPage( )	AcBasePage	Returns this page itself.
GetPageIndex( )	Integer	Returns the page index for the page.
GetPageNumber( )	String	Returns the formatted page number.
PageNumberFormat( )	String	Returns the page number format.
Considerations for HTML reports

HTML documents are all one long page. HTML does not support the concept of page breaks. Therefore, the AFC ignores pagination classes, including this one, when generating HTML for a report.


Methods for class AcPage

AcPage::FormatPageNumber method

AcPage::GetPage method

AcPage::GetPageIndex method

AcPage::GetPageNumber method

AcPage::PageNumberFormat method


AcPage::FormatPageNumber method

See also

Returns the formatted page number.

Syntax

Function FormatPageNumber( pageIndex As Integer ) As String

pageIndex

The index of the current page.

Description

The default is to format the index using the PageNumberFormat( ) method. Override this method to perform custom page number formatting.

Return value

Returns the formatted page number.


See also

AcPage::PageNumberFormat method


AcPage::GetPage method

See also

Returns the current page.

Syntax

Function GetPage( ) As AcBaseFrame

Description

This method gets the current page.

Return value

Returns the current page.


See also

AcPageList::GetPage method

AcReportComponent::GetPage method

AcVisualComponent::GetPage method


AcPage::GetPageIndex method

See also

Returns the page index of the current page.

Syntax

Function GetPageIndex( ) As Integer

Description

This method gets the current page index. The page index starts with the first page being page 1.

Return value

Returns the page index, starting with 1, for the page within the report.


See also

AcBaseFrame::GetPageIndex method

AcReportComponent::GetPageIndex method


AcPage::GetPageNumber method

See also

Returns the formatted page number.

Syntax

Function GetPageNumber( ) As String

Description

This method returns the formatted page number as a string. The formatted page number may or may not be the same as the page index. For example, the formatted page number can take the form 3-6, iii, or C-7.

Return value

Returns the formatted page number of the current page as a string.


See also

AcBaseFrame::GetPageNumber method


AcPage::PageNumberFormat method

Returns the page number format.

Syntax

Function PageNumberFormat( ) As String

Description

Returns the page number format property as a string. The format must be a format acceptable to the Format$( ) function. The default is "".

Return value

The page number format property as a string.


Class AcPageList

Methods

Instantiates and holds the pages for a report.

Description

The class AcPageList instantiates and holds the pages for a report. AcPageList is an abstract class with methods for all types of page lists. Derived classes provide the organization of the pages within the page list.

Page structure

The Actuate framework page structure consists of a page list, pages, flows, and frames. A page list can contain multiple pages, a page can contain multiple flows, and a flow can contain multiple frames. The following illustration shows the page structure of page list, page, flow, and frame.

The page structure scheme works as follows: A page list receives a frame from a section. The page list then attempts to place that frame on the current page. The page attempts to place the frame in the current flow. If there is room for the frame on the current page, the flow places the frame on the page. If there is not room on the page for the frame, the page list builds another page. The framework then places the frame on the new page.

The previous illustration also shows the roles of a data stream and section in building a report. The data stream supplies data rows to the section. The data stream is not concerned with how those data rows will be placed in a frame; that is the responsibility of the section.

The section builds frames from the data rows supplied by the data stream and hands them off to the page list. The section is not concerned with how those frames are placed on the page; that is the role of the page list. In the simplest case, the section does not respond to any events--it just feeds frames to the page list. In a more advanced case, the section can respond to events such as a page break and send special frames such as headers and footers to the page list when needed.

A section can also contain logic that causes the page list to eject a page. For example, the section could generate a blank even numbered page at the end of the section if it is needed for double-sided printing.

Page and content structures

The page structure is connected to the content structure at both the top and bottom ends. The following figure illustrates how the page structure and content structure relate to each other. The structures are connected at the top by a report object and at the bottom by frames.

Current page

When the page list is running, it always has knowledge of the first and last pages. Normally, the page list also has knowledge of the current page. However, there are times when the page list does not have a current page. For example, when a page is ejected and before another page is built, the page list does not have a current page. The page list must build another page, but delays that decision as late as possible. Specifically, if a section has the PageBreakAfter property set to True, the page list will not have a current page until it receives another frame. The following figure illustrates the state of the page list after page 4 is ejected. The page list does not point to any page; that is, the connection to the current page is broken.

Subclassing AcPageList

AcPageList is an abstract class for all types of page lists. The derived classes define the organization of the pages in the page list. The Actuate framework provides three derived classes from AcPageList:

•	AcSimplePage List builds a page list with a series of body pages all of the same style.

•	AcLeft RightPage List builds a page list with alternating left-right pages.

•	AcTitleBodyPage List builds a page list with a title page, followed by a simple page list.

Variables

Variable	Type	Description
Pages	AcList	The list of all pages in the page list.
Methods

Method	Type	Description
AddComponent( )	N/A	Adds a report component to the page list.
AddFrame( )	AcPageList	Adds a frame to the page list.
EjectPage( )	N/A	Finishes the currently active page.
GetCurrentFlow( )	AcFlow	Returns the currently active flow on the current page
GetCurrentPage( )	AcPage	Returns the current page in the page list.
GetEstimatedPageCount( )	Integer	Provide an estimate of the number of pages a report will contain.
GetFirstPage( )	AcPage	Returns the first page in the page list.
GetLastPage( )	AcPage	Returns the last page in the page list.
GetPage( )	AcPage	Returns the indexed page in the page list.
GetPageCount( )	Integer	Returns the number of total pages in the page list.
NeedHeight( )	N/A	Ensures that a specified amount of vertical space is available in the current flow, and if not, starts a new flow.
NewPage( )	AcPage	An empty method that derived classes override to instantiate a new page.
PopPageFooter( )	N/A	Cancels the most recently added page footer.
PopSection( )	N/A	Tells the page list that a section is no longer active.
PopSubpage( )	Boolean	Deregisters the currently active subpage with the page list.
PushPageFooter( )	Boolean	Adds a page footer to the current flow for the current sections.
PushPageHeader( )	Boolean	Adds a page header to the current flow for the current sections.
PushSection( )	N/A	Tells the page list that a section is becoming active.
PushSubpage( )	Boolean	Registers a subpage with the page list.
ShiftFooterUp( )	N/A	Shifts the page footer up to just after the last frame in the flow.
Considerations for HTML reports

HTML documents are all one long page. HTML does not support the concept of page breaks. Therefore, the AFC ignores pagination classes, including this one, when generating HTML for a report.


Methods for class AcPageList

AcPageList::AddComponent method

AcPageList::AddFrame method

AcPageList::EjectPage method

AcPageList::GetCurrentFlow method

AcPageList::GetCurrentPage method

AcPageList::GetEstimatedPageCount method

AcPageList::GetFirstPage method

AcPageList::GetLastPage method

AcPageList::GetPage method

AcPageList::GetPageCount method

AcPageList::NeedHeight method

AcPageList::NewPage method

AcPageList::PopPageFooter method

AcPageList::PopSection method

AcPageList::PopSubpage method

AcPageList::PushPageFooter method

AcPageList::PushPageHeader method

AcPageList::PushSection method

AcPageList::PushSubpage method

AcPageList::ShiftFooterUp method


AcPageList::AddComponent method

Adds a report component to the page list.

Syntax

Sub AddComponent( component As AcReportComponent )

component

The component to add to the page list.

Description

Sections call AddComponent( ) to add a report component to the page list. The page list checks if the component is a frame. If so, the page list adds that frame to the current page. This method allows sections to treat frames and sections identically, allowing either to be added to the page list.


AcPageList::AddFrame method

See also

Adds a frame to the page list.

Syntax

Sub AddFrame( frame As AcFrame )

frame

The frame to add to the page list.

Description

The AddFrame method adds a frame to the page list. If there is a current page, and the frame will fit on that page, AddFrame places the frame on the page.

A frame can contain information about what page it is to appear. For example, if the frame needs has the PageBreakBefore property set, AddFrame will eject the current page and instantiate a new page before placing the frame on the new page.

•	When the page list does not have a current page, (e.g., a page has just been ejected), AddFrame instantiates a new page. It does so by asking each active component in the content hierarchy to instantiate a page by calling the NewPage( ) method, starting with the frame passed to AddFrame( ).

•	Normally, the frame does not contain page information--it doesn't care where it gets placed on the page. In this case, the page list traverses up the content structure searching for page placement information from successively higher branches. If the search goes all the way to the top, then the page list instantiates the default page as defined in the page list subclass.

•	When the page list does have a current page, the page list determines whether the frame will fit. If so, it just places the frame on the current page. If not, the page list ejects the current page, instantiates a new page, and places the frame on the new page.

Once the frame is placed on a page, the page list determines if the frame has the PageBreakAfter property set. If so, the page list ejects the page; if not, the process of adding frames continues.

Normally, you should not override AddFrame.


See also

AcFlow::AddFrame method

AcTopDownFlow::AddFrame method


AcPageList::EjectPage method

Finishes the currently active page.

Syntax

Sub EjectPage( )

Description

The EjectPage( ) method finishes the currently active page. If no page is active, EjectPage( ) does nothing.


AcPageList::GetCurrentFlow method

Returns the currently active flow on the current page.

Syntax

Function GetCurrentFlow( ) As AcFlow

Description

The currently active flow is the flow in which the Factory is currently placing components.

Return value

The currently active flow (if any) on the current page (if any).

Nothing if no flow is active.


AcPageList::GetCurrentPage method

Returns the current page in the page list.

Syntax

Function GetCurrentPage( ) As AcPage

Description

The current page is the page on which the Factory is currently placing and filling flows.

Return value

The current page.


AcPageList::GetEstimatedPageCount method

Example

Provide an estimate of the number of pages needed for this report.

Syntax

Function GetEstimatedPageCount( ) As Integer

Description

GetEstimatedPageCount( ) allows you to optimize the layout of data in the ROI. Override this method to provide an estimate of the number of pages that the report will contain. This allows the AFC to pre-allocate parts of the report. Pre-allocating parts of the report reduces the number of reads required to view the report.

The estimate is accurate to a power of 50.  For example, providing a value of 1 works for reports up to 50 pages long.  Providing a value of 51 handles reports up to 2500 pages long.  Try to be as accurate as possible when you provide the estimate.


Example

Function GetEstimatedPageCount( )

GetEstimatedPageCount = 100

End Function


AcPageList::GetFirstPage method

Returns the first page in the page list.

Syntax

Function GetFirstPage( ) As AcPage

Description

The page list holds all the pages for the report. This method gets the first page in the list.

Return value

The first page in the page list.


AcPageList::GetLastPage method

Returns the last page in the page list.

Syntax

Function GetLastPage( ) As AcPage

Description

The page list holds all the pages in the report. This method gets the last page added to the report.

Return value

If you call GetLastPage( ) in the Viewer, GetLastPage( ) returns the last page of the page list.

If you call GetLastPage( ) in the Factory, it returns the last page that currently exists. For example, if you call GetLastPage( ) when the report is partially built, GetLastPage( ) returns the current page.


AcPageList::GetPage method

Returns the indexed page in the page list.

Syntax

Function GetPage( index As Integer ) As AcPage

index

The number of the page to retrieve.

Description

The GetPage( ) method returns the page for the index that you supply to the method. The index is an integer and the page numbers begin with one.

If the index does not correspond to an actual page in the page list, GetPage( ) returns Nothing.


AcPageList::GetPageCount method

Returns the number of pages in the page list.

Syntax

Function GetPageCount( ) As Integer

Description

The GetPageCount( ) method returns the number of pages in the page list. If called before the page list is complete, GetPageCount( ) returns the number of pages processed so far.

Return value

The number of pages in the page list.


AcPageList::NeedHeight method

Ensures that a specified amount of vertical space is available in the current flow, and if not, starts a new flow.

Syntax

Sub NeedHeight (Height As Integer)

Description

Request a certain amount of vertical space in the current flow. Request a new flow if the requested vertical space cannot fit in the current flow. Space is measured in twips.


AcPageList::NewPage method

Example

Instantiates a new page.

Syntax

Function NewPage( ) As AcPage

Description

The page list calls this method to instantiate each new page. If you use one of the predefined page classes, the framework creates the page for you based on the components you add to the page list in the structure pane. If you create your own custom page list class, you must override this method.


Example

The following example shows how to create different page designs for two reports that run in sequence: a customer list and an order list. To view the code used in this example in a fuller context, open Examples\CASE-STMT.ROD, highlight the SequentialSection component, and examine the component's overridden NewContent( ) and NewPage( ) methods. Note SequentialSection's custom variable, TestIndex.

In the following code example, the custom variable TestIndex has a value of 1 when the first of the two sequential reports runs. When the second report runs, TestIndex has a value of 2.

Function NewContent( index As Integer ) As AcReportComponent

Set NewContent = Super::NewContent( index )

' Insert your code here

TestIndex = index

End Function

The next code example passes the value of TestIndex to the NewPage( ) method, so that the NewPage( ) method will know whether to instantiate either the CustomerPage, or the OrderPage component.

In CAST-STMT.ROD, both of the page components are predesigned, but invisible in the default Design View. You can view them in Project View, and inspect them via Edit Layout.

The call to Super::NewPage( ) is commented out.

Function NewPage( ) As AcPage

' Set NewPage = Super::NewPage( )

' Insert your code here

Select Case TestIndex

Case 1

Set NewPage = New Persistent CustomerPage

Case 2

Set NewPage =  New Persistent OrderPage

End Select

End Function

Return value

The new page instantiated.


AcPageList::PopPageFooter method

See also

Cancels the most recently added page footer.

Syntax

Sub PopPageFooter( )

Description

The PopPageFooter method cancels the most recently added page footer. You might call this method if you realize that your section will end on the current page, and that you therefore do not need the page footer after all. You should call this method only from a section's FinishFlow( ) method. This method is called automatically for report and group sections.


See also

AcPageList::PushPageFooter method

AcSection::FinishFlow method


AcPageList::PopSection method

See also

Tells the page list that a section is no longer active.

Syntax

Sub PopSection( )

Description

The PopSection( ) method tells the page list that a section is no longer active. The section calls this method in the page list to deregister itself with the page list. After this call, the page list will no longer call the section's StartFlow( ), FinishFlow( ), and other methods each time a new flow starts or ends. The framework makes this call automatically for the standard AFC sections.


See also

AcPageList::PushSection method

AcSection::StartFlow method


AcPageList::PopSubpage method

See also

Deregisters the currently active subpage with the page list.

Syntax

Sub PopSubpage( )

Description

The PopSubpage( ) method tells the page list that the currently active subpage is no longer needed. This method is called automatically for sections with a subpage.


See also

AcPageList::PushSubpage method


AcPageList::PushPageFooter method

See also

Adds a page footer to the current flow for the current sections.

Syntax

Function PushPageFooter( footer As AcFrame ) As Boolean

footer

The frame to become the page footer.

Description

The PushPageFooter( ) method adds a page footer to the current flow for the current sections. Page footers are nested with the uppermost section placing the bottom page footer, and the innermost section placing the topmost page footer. You should call this method only from a section's StartFlow( ) method. This method is called automatically for report and group sections.

Return value

True if the page footer was added to the current flow.

False if the page footer was not added to the current flow.


See also

AcSection::StartFlow method


AcPageList::PushPageHeader method

See also

Adds a page header to the current flow for the current sections.

Syntax

Function PushPageHeader( header As AcFrame ) As Boolean

header

The frame to become the page header.

Description

The PushPageHeader( ) method adds a page header to the current flow for the current sections. Page headers are nested with the uppermost section placing the topmost page header, and the innermost section placing the bottommost page header. You should call this method only from a section's StartFlow( ) method. This method is called automatically for report and group sections.

Return value

True if the page header was added to the current flow.

False if the page header was not added to the current flow.


See also

AcSection::StartFlow method


AcPageList::PushSection method

See also

Tells the page list that a section is becoming active.

Syntax

Sub PushSection( section As AcSection )

section

The section that is becoming active.

Description

The PushSection( ) method tells the page list that a section is becoming active. The section calls this method in the page list to register itself with the page list. While a section is registered, the page list will call the section's StartFlow( ), FinishFlow( ), and other methods each time a new flow starts or ends. The framework makes this call automatically for the standard AFC sections.


See also

AcPageList::PopSection method

AcSection::StartFlow method


AcPageList::PushSubpage method

See also

Registers a subpage with the page list.

Syntax

Function PushSubpage( subpage As AcSubpage ) As Boolean

subpage

The subpage to activate.

Description

The PushSubpage( ) method registers a subpage with the page list. The page list will direct any future frames added to the page list into the subpage. The subpage is automatically deregistered at the end of the current flow. (Sections must create a new subpage for every new flow.) You should call this method only from a section's StartFlow( ) method. This method is called automatically for sections with a subpage.

Return value

True if the subpage was added to the current flow.

False if the subpage was not added to the current flow.


See also

AcPageList::PopSubpage method

AcSection::StartFlow method


AcPageList::ShiftFooterUp method

See also

Shifts the page footer up to just after the last frame in the flow.

Syntax

Sub ShiftFooterUp( )

Description

By default, a page footer appears along the bottom of a flow. You can choose, instead, to display the page footer just after the last frame in the flow. This method shifts up the page footer for the currently active section. You should call it only from a section's FinishFlow( ) method. This method is called automatically for report and group sections when the sections ContiguousPageFooter property is True.


See also

AcFlow::ShiftFooterUp method

AcSection::FinishFlow method


Class AcParallelSection

Methods

A class that fills two or more flows on the page.

Description

A parallel section contains two or more subreports that appear in different flows on the same page. For example, a parallel section can present two different reports side by side.

Consider a page that has multiple flows on it. AcParallelSection fills each flow with a different data stream, filling each flow until it is full, then progressing through the remaining flows on the page until the entire page is full. Then, a new page is built and the process of filling each flow continues, until all data streams have been processed.

When building a parallel section you must establish the relationship between reports in the parallel section and flows on the page. You do so by setting the report section's FlowName property to the name of the flow in which the report should appear. For example, if you create a page with two flows, Flow1 and Flow2, set the FlowName property of the first report to Flow1 and the FlowName property of the second report to Flow2.

Your parallel section must have access to the correct page that contains the necessary flows. You can provide this page in one of three ways:

•	First, if the only item in your report is the parallel section, then you can use a simple page list, and make sure that the page in that page list has the correct number of flows with the correct tags.

•	You can override the NewPage( ) method to instantiate the page you want to use within the parallel section. This page takes precedence over any page that the page list provides. If you do this, be sure to set the PageBreakBefore and PageBreakAfter properties to True so that the parallel section starts on the correct page, and no other components use the special page.

•	You can provide a subpage that will fit inside the flow on your standard page. To do this, drop a subpage component in the Subpage slot of the parallel report.

The parallel section class is complex; it is usually best to use its methods as-is rather than override them. The exceptions are the methods which affect the formatting of parallel sections in HTML reports. Those HTML-related methods are documented here.

Building the nested reports

The nested reports are built in the parallel section's Build( ) method. The following is the sequence used to build the section:

1	Instantiate and start all of the nested reports.

2	Locate the first page.

3	For each report that still has rows to produce, locate the corresponding flow using the report and flow's Tag property. Then, run the report until it fills up its flow.

4	Eject the page.

5	If any reports have more rows to produce, loop back to step 2 to locate the next page and repeat the process.

Properties

Property	Type	Description
Content	AcReport	The list of nested reports to appear in the parallel report.
Considerations for HTML reports

Actuate converts parallel sections to HTML tables when creating HTML reports. By default, the HTML table consists of one row and several columns, one for each parallel section in the report. The browser determines the width of each column at run time.

You can manipulate the format of the HTML tables by overriding the methods listed in this section.

You must provide flows so that the report will build. However, the flows have no effect on the way the HTML output displays.

Methods

Method	Type	Description
FillEmptyHtmlCells( )	Boolean	True to fill empty parallel sections with color; False otherwise.
GetHtmlBorderWidth( )	Integer	Returns the width of the border around the table. 0 means there is no border.
GetHtmlCell( )	AcReportSection	Returns the report to display in a particular parallel section (HTML table cell).
GetHtmlCellAlignment( )	AcTextVertical Placement	Determines how to align the contents of the parallel section (HTML table cell): top, bottom, or middle.
GetHtmlColumnCount( )	Integer	Determine how to lay out the reports contained in parallel sections as cells in an HTML table.
GetHtmlRowCount( )	Integer	Determine how to lay out the reports contained in parallel sections as cells in an HTML table.
GetHtmlTableColor( )	AcColor	Returns the default background color for the parallel section (HTML table cell).


Methods for class AcParallelSection

AcParallelSection::FillEmptyHtmlCells method

AcParallelSection::GetHtmlBorderWidth method

AcParallelSection::GetHtmlCell method

AcParallelSection::GetHtmlCellAlignment method

AcParallelSection::GetHtmlColumnCount method

AcParallelSection::GetHtmlRowCount method

AcParallelSection::GetHtmlTableColor method


AcParallelSection::FillEmptyHtmlCells method

Determines whether or not to fill empty HTML table cells with color.

Syntax

Function FillEmptyHtmlCells( ) As Boolean

Description

FillEmptyHtmlCells( ) determines whether or not to fill empty HTML table cells with color. Override this method to set whether or not to fill empty HTML table cells with color.

Return value

True to fill empty cells with color; False otherwise.


AcParallelSection::GetHtmlBorderWidth method

Returns the width of the border around the HTML table.

Syntax

Function GetHtmlBorderWidth( ) as Integer

Description

GetHtmlBorderWidth( ) returns the width of any border around the HTML table. If there is no border, GetHtmlBorderWidth( ) returns 0. Override this method to determine the width of the border around the HTML table.

Return value

The width of the border around the HTML table, or 0 if there is no border.


AcParallelSection::GetHtmlCell method

Returns the report to display in an HTML table cell, specified by its row and column in the HTML table.

Syntax

Function GetHtmlCell ( Row As Integer, Column As Integer )
As AcReportSection

Row

The HTML table cell's row.

Column

The HTML table cell's column.

Description

GetHtmlCell( ) returns the report to display in an HTML table cell. Specify the cell's location using row and column. If the cell is empty, GetHtmlCell returns the special value Nothing. Override this method to determine the report to display in the HTML table cell.

Return value

The report that the given table cell displays, or Nothing.


AcParallelSection::GetHtmlCellAlignment method

Determines how to align the contents of the HTML table cell.

Syntax

Function GetHtmlCellAlginment ( ) As AcTextVerticalPlacement

Description

GetHtmlCellAlignment( ) determines how to align the contents of the HTML table cell: top, bottom, or middle. The default is to align the contents at the top of the cell. Override this method to align cell contents to the middle or bottom of the cell.


AcParallelSection::GetHtmlColumnCount method

Determines how to lay out parallel reports in an HTML table.

Syntax

Function GetHtmlColumnCount( ) As Integer

Description

GetHtmlColumnCount( ) determines how to lay out parallel section reports as HTML tables in an HTML report. The default is to format the parallel reports as a series of columns in an HTML table. Override GetHtmlColumnCount( ) and GetHtmlRowCount( ) to change this to any rectangular grid shape.


AcParallelSection::GetHtmlRowCount method

Determines how to lay out parallel reports in an HTML table.

Syntax

Function GetHtmlRowCount( ) As Integer

Description

GetHtmRowCount( ) determines how to lay out parallel section reports as HTML tables in an HTML report. The default is to format the parallel reports as a series of columns in an HTML table. Override GetHtmlColumnCount( ) and GetHtmlRowCount( ) to change this to any rectangular grid shape.


AcParallelSection::GetHtmlTableColor method

Returns the default color for cells in the HTML table.

Syntax

Function GetHtmlTableColor( ) As AcColor

Description

GetHtmlTableColor( ) returns the default color for the cells in the HTML table. The value TransparentColor means that the cells show the default background color for the HTML page. Override this method to set the default background color for the HTML table.


Class AcPopupMenu

Methods

Allows the user to create pop-up menus in Basic.

Description

The AcPopupMenu class lets you create context menus. You create and use menus in the Viewer in response to user actions, usually right mouse clicks. You respond to these user actions by overriding the set of user event methods in AcVisualComponent. Using the methods in AcPopupMenu, you can modify the standard menu or create your own menu. As a convenience, Actuate automatically creates a menu in response to the right mouse button.

The methods in the AcPopupMenu class closely parallel their Windows Software Development Kit (SDK) counterparts. These methods are independent of the AFC class hierarchy, which means that you can create pop-up menus anywhere in your Viewer code.

To create a pop-up menu, populate it with menu items. Enable or disable menu items as appropriate. Add cascading menus if you want. Finally, call Run( ) to display or check the menu and let the user make a choice.

The menu works by associating subroutines with the menu items. The subroutine can be a method on the menu itself or a method on another object.

When you instantiate a pop-up menu, the AFC framework creates a new instance of the pop-up menu and attaches it to the given view. The view must be an AcReportView provided as an argument to each of the user action methods.

Variables

Variable	Type	Description
View	AcReportView	The view to which to add a menu.
Methods

Method	Type	Description
AddCascade( )	Integer	Adds a cascading menu.
AddItem( )	Integer	Adds a menu command that binds to a method in an object.
AddSeparator( )	N/A	Adds a menu separator.
CheckMenuItem( )	N/A	Places or removes a checkmark next to the menu item.
EnableMenuItem( )	N/A	Enables or disables a menu item.
MakeMenu( )	N/A	Override this method in a subclass to add default menu items to the subclass.
Run( )	Integer	Executes a menu.


Methods for class AcPopupMenu

AcPopupMenu::AddCascade method

AcPopupMenu::AddItem method

AcPopupMenu::AddSeparator method

AcPopupMenu::CheckMenuItem method

AcPopupMenu::EnableMenuItem method

AcPopupMenu::MakeMenu method

AcPopupMenu::Run method


AcPopupMenu::AddCascade method

Adds a cascading menu.

Syntax

Function AddCascade( command As String, cascade As AcPopupMenu ) As Integer

command

The text string to identify the cascading menu as a parent menu.

cascade

The cascading menu to add to the parent menu.

Description

The AddCascade( ) method adds a cascading menu to the parent menu and returns the integer position of the cascading menu. A cascading menu is a submenu with each of its menu items renumbered from one. You must create the menu first, then add it to its parent menu. The command argument is the text to place in the parent menu. The command is added at the end of the parent menu.

Return value

The menu ID of the cascade menu added.


AcPopupMenu::AddItem method

Example

Adds an item to the menu.

Syntax

Function AddItem( command As String, method As String) As Integer

Function AddItem( command As String, obj As AnyClass, method As String )
As Integer

command

The text string of the menu command.

method

The method to associate with the menu command.

obj

The class that contains the method to associate with the menu command.

Description

The AddItem( ) method adds an item to the end of the menu, from the top down. The command parameter is the text of the menu item, such as "&Copy" or "Follow &Link". The menu item can have an embedded ampersand, which shows the access key for the menu in the standard Windows fashion. A double ampersand (&&) in the menu command string results in a single displayed ampersand (&). The return value is the position of the menu item in the menu, and is the value that the user must pass to the EnableMenuItem method, CheckMenuItem method, and so on.

Menu items are enabled and unchecked by default.

•	Use the first form of AddItem( ) to call methods on the menu class itself.

•	Use the second form when the method is defined in another class. The method must be defined in the class the 'obj' represents.

Every menu command causes an action. You specify the action in one of two ways: First, you can call a method on the menu class itself. Second, you can call a method on some other object. In either case, the method must be a function that takes the same arguments as the user action methods on an AcVisualComponent, and must return a Boolean.


Example

Function ShowHelp( view As ReportView, x As Integer, y As Integer ) As Boolean

...

End Function

Return value

The ID of the item added to the menu.


AcPopupMenu::AddSeparator method

Adds a separator (line) to the menu.

Syntax

Sub AddSeparator( )

Description

The AddSeparator( ) method adds a separator to the end of the menu.


AcPopupMenu::CheckMenuItem method

Checks or unchecks a menu item.

Syntax

Sub CheckMenuItem( item As Integer, check As Boolean)

item

The ID number of the menu item returned from AddItem( ).

check

True if the item is to be checked; False if the item is to be unchecked.

Description

The CheckMenuItem takes a menu item index, and checks or unchecks the menu item. A checked menu item displays a checkmark next to the item.


AcPopupMenu::EnableMenuItem method

Enables or disables a menu item.

Syntax

Sub EnableMenuItem( item As Integer, enable As Boolean )

item

The ID number of the menu item returned from AddItem( ).

enable

True to enable the item, False to disable the item.

Description

The EnableMenuItem takes a menu item index, and enables or disables the menu item. A disables menu item appears in gray.


AcPopupMenu::MakeMenu method

Initializes a menu.

Syntax

Sub MakeMenu( )

Description

The MakeMenu( ) method is called by the AFC framework when a menu is instantiated. Use this method to add, enable, and check default menu items for the class.

You can override this method in a subclass of AcPopupMenu. Most of the time, however, there is no need to subclass AcPopupMenu.


AcPopupMenu::Run method

Executes a menu.

Syntax

Function Run( ) As Integer

Description

This method displays the menu and tracks user actions. When the user selects one menu item, the method associated with that menu item is executed.

The Run( ) method executes the menu you have created. The function returns zero if the user closed the menu without selecting anything. If the user selects a command, Run( ) calls the associated method, then returns the menu item ID number of the selected item. Menu ID numbers start at one and correspond to the position within the menu.

If the user chooses an item in a cascading menu, the ID number returned is the ID within the pop-up menu.

Return value

The ID of the menu item executed.


Class AcProgressConnection

Establishes a connection to a Progress Software database.

Description

Use the AcProgressConnection class to establish a connection to a Progress database. The application must set the database list and startup parameters prior to connecting. Once connected, the application should not change these values.

Variables

Variable	Type	Description
DatabaseList	string	Database name.
DllPath	string	Actuate/Progress interface software.
Password	string	User's Progress database password.
StartUpParameters	string	Progress Open Interface Broker parameters.
UserName	string	Login name for the Progress database.
Properties

Property	Type	Parameter	Description
DatabaseList	string	-db <db-name>	Database name.
		-S <db-port>	Registered TCP socket name. Must be different than <broker-port>.
		-N TCP	Connection protocol, TCP specifies TCP/IP.
		-H <db-host>	Database host computer name.
Dllpath	string	ESQL32.DLL	Actuate/Progress interface software.
Password	string		User's Progress database password.
StartUpParame- ters	string	-SV	Specifies Small Client behavior. This must be the first parameter.
		-S  <broker-port>	Registered TCP socket name. Must be different than <db-port>.
		-N TCP	Connection protocol, TCP specifies TCP/IP.
		-H  <broker-host>	Open Interface Broker host computer name.
UserName	string		Login name for the Progress database.
When you connect to a Progress Database through Actuate, you must specify settings using DatabaseList and StartUpParameters. For DatabaseList, you must use -db, -H, and -S to log into the database. For StartUpParameters, you must specify -SV, -H, -S and, -N to log into the Progress Open Interface Broker (OIB).

If Progress Security is active, you can use the following optional DatabaseList parameters to specify a user name and password:

•	-U <username> User name registered to Progress Security.

•	-P <password> User's password.

You can log into multiple databases using different user name and password combinations. For example, you can enter this string for the DatabaseList parameter to log into the sports and mktg databases:

-db sports -H ahost -S asvc -U aname -P apass -db mktg -H bhost -S bsvc
-U bname -P bpass

Using UserName or Password is equivalent to using the -U and -P parameters. Actuate uses the name and password for each database in the DatabaseList. For example, if you use:

DatabaseList = "-db adb -H ahost -S asvc -db bdb -H bhost -S bsvc"

UserName = "fred"

Password = "apass"

Actuate creates this database list string:

-db adb -H ahost -S asvc -U fred -P apass -db bdb -H bhost -S bsvc -U fred
-P apass

Progress data types

The following table describes the default conversion between Actuate data types and Progress data types.

Progress data type	Mapped to
Array	The native syntax. The native syntax would appear as follows in an Actuate report design: tablename.array1[1]
Character	Actuate String. Can also be mapped to (given a datatype correct string) an Actuate Boolean, Currency, Date, Double, Integer, Long, Single, or Variant.
Date	Actuate Date. Can also be mapped to an Actuate String or Variant.
Logical	Actuate Integer. Can also be mapped to an Actuate Boolean, Long, or Variant.
Integer	Actuate Integer. Can also be mapped to an Actuate Boolean, Currency, Double, Long, Single, String, or Variant.
Decimal	Actuate Double. Can also be mapped to an Actuate Boolean, Currency, Double, Integer, Long, Single, String, or Variant.
Raw	Actuate Double.
Recid	Actuate Integer.
Currency data type

Although there is no currency data type in Progress, a Progress decimal, integer, or character (in an appropriate format) can be mapped to an Actuate currency value and converted correctly.

Databases and queries

Actuate supports accessing multiple Progress databases concurrently. Within an Actuate connection object it is possible to identify a list of databases you want to access within that connection. This lets you create joins between tables in different Progress databases.

When using expressions in Actuate, you can give an expression a name. For example, in an Actuate query, this statement defines extendedPrice:

"(price * quantity)" as extendedPrice

The name extendedPrice becomes a name that can be used elsewhere in the query, for example, in the WHERE clause or in the ORDER BY clause. For Progress databases, Actuate replaces the name with the actual expression before sending the query to the database.


Class AcRecordBuffer

See also   Methods

A data filter that converts a sequential data stream into one allowing random access by buffering data rows on disk.

Description

Many data sources provide only the ability to read rows in a sequential first-to-last order. However, there are times when you need to move through the data in random order, perhaps making multiple passes over certain groups of data to print the data first in a graph, then in a tabular format. The AcRecordBuffer class acts as a converter to change a sequential data source into a random-access data stream. It does so by storing (buffering) data rows on disk as you read them so that you can return back to them again later. You don't need to use this class if your data source already provides random access.

This class is similar to the AcMemoryBuffer class, except that it allows you to handle larger numbers of rows. You must also ensure that AcRecordBuffer can create and return persistent copies of the input data rows.

Because this data filter supports random access, the CanSeek( ) method returns True, and all the various random-access methods such as SeekTo( ) and Rewind( ) are available.

AcRecordBuffer lets you manipulate data as if you had direct access to the input source. You can locate rows by specifying a row number with SeekTo( ) or by specifying a relative position with SeekBy( ). You can rewind to the beginning of the data buffer with Rewind( ) or advance to the end with SeekToEnd( ). The row number starts at 1. (See AcDataAdapter for details.)

Although not required, you may choose to flush the buffer occasionally to remove from memory those rows that you no longer need. For example, if you need to make two passes over the data for each customer, you can flush the rows for each customer as you complete the process. Flushing the buffer causes no change to the way you access rows; you just won't be able to seek back to revisit the flushed rows. See the FlushBuffer( ) and FlushBufferTo( ) methods for details.

Methods

Method	Type	Description
AddRowToBuffer( )	N/A	Programmatically adds a row to the data row buffer.


See also

Class AcMemoryBuffer


Methods for class AcRecordBuffer

AcRecordBuffer::AddRowToBuffer


AcRecordBuffer::AddRowToBuffer

Adds a row to the data row buffer.

Syntax

Sub AddRowToBuffer ( row As AcDataRow )

row

The data row to add to the buffer.

Description

AddRowToBuffer() adds the specified row to the end of the buffer. Use this method to programmatically add a row to the buffer on disk. This method does not modify the current read position.


Class AcRectangleControl

A class you use the report design to display a rectangle.

Description

A rectangle is a content control that is fully defined at design time. You can specify its color, size, and the curve of its corners. Using the two Rounding properties, X and Y, you specify numeric values to control the roundness of the rectangle's corners. The higher the numbers, the rounder the corners. Actuate creates rounded corners by centering an ellipse in the rectangle, and clipping the area within the borders of the rectangle and the ellipse, as the following illustration shows.

Variables

Variable	Type	Description
FillColor	AcColor	The color with which to fill the shape.
LineStyle	AcLineStyle	The style of line to draw around the shape.
Rounding	AcRounding	The amount of rounding to use for the corners of the rectangle.
Properties

Property	Type	Description
FillColor	AcColor	The color with which to fill the shape.
LineStyle	AcLineStyle	The style of line to draw around the shape.
Rounding	AcRounding	The amount of rounding to use for the corners of the rectangle.
Considerations for HTML reports

HTML does not provide a rectangle graphic. Therefore, the Actuate rectangle control is not supported in HTML reports.  If you include a rectangle control in your design, AFC ignores it when generating the HTML output.


Class AcReport

See also   Methods

AcReport is the root object that contains all objects in a report.

Description

Like the main program in an application, the report object is the entry point to the report. In the structure pane, the report object appears at the top. Immediately contained within it are the

•	ReportSection--the topmost container of the content elements.

•	PageList--the topmost container of the display elements.

The report section starts the processes for building the report and for displaying the report at run time.

To build the report, the report object

•	Starts the PageList creation process.

•	Starts the content creation process.

The Design Editor automatically generates a subclass of AcReport for every new report. You can then subclass that subclass to make a copy of the original report.

Because the report object controls the report-building process, you should be careful when overriding its methods. To add startup or cleanup code (for example, to initialize global variables or close files) override Start( ) and Finish( ). The Factory calls Start( ) before it begins generating the report, and Finish( ) after it generates the report.

Variables

Variable	Type	Description
Pages	AcPageList	The object that holds the list of pages.
Root	AcReportComponent	A reference to the first element in the report. From this element, the application can traverse down to all other frame records in the report.
Properties

Property	Type	Description
PageList	AcPageList	The PageList style to use when creating pages for report output.
Content	AcReportComponent	The top-most (or only) report section for a report.
CustomRequesterName	String	The executable (.EXE) file that launches a custom requester window. This custom window replaces Actuate's Requester dialog box that appears when users run a report.
Methods

Method	Type	Description
Finish( )	N/A	Called after the Factory has finished building the report.
GetContent( )	AcReport Component	Returns the top-most component in the report.
GetPageList( )	AcPageList	Returns the list of pages in the report.
GetTwipsPer Pixel( )	Integer	Sets the twips-to-pixel conversion factor.
NewContent( )	AcReport Component	Creates the top-level report element. (Generated.)
NewPageList( )	AcPageList	Creates the page list for the report. (Generated.)
OnFinishViewer( )	N/A	Called by the viewer before it closes the report (.ROI) file. (Empty.)
OnStartViewer( )	N/A	Called by the viewer before it opens the report (.ROI) file. (Empty.)
Start( )	N/A	Called at the start of the Factory.
SuggestRoiName ( )	String	Called to suggest the ROI name for this report.


See also

Class AcPageList


Methods for class AcReport

AcReport::Finish method

AcReport::GetContent method

AcReport::GetPageList method

AcReport::GetTwipsPerPixel method

AcReport::NewContent method

AcReport::NewPageList method

AcReport::OnFinishViewer method

AcReport::OnStartViewer method

AcReport::Start method

AcReport::SuggestRoiName method


AcReport::Finish method

Example

Called after the Factory has finished building the report.

Syntax

Sub Finish( )

Description

Actuate calls Finish( ) after the Factory has generated the report, but before the report file is closed. Override Finish( ) to add cleanup code or additional processing, for example, to send completion notices or write statistics to a log file. Call Super::Finish( ) after your custom code to ensure that the Factory executes the original code as well.


Example

This example shows how to number the pages in your report in the style of "Page 7 of 90". You can see the code used in this example in a fuller context. To do so, open Examples\v0.rod and examine the Report component's overridden Finish method.

You can extend this example to any situation where you want to display a value that cannot be calculated until the entire report is finished. For example, use this technique to show a grand total on the first page of a report, or to display a value on each page that expresses a percentage of some total value.

The pageno.rod example includes a label control called PageNoDisplay. To see it, expand the PageList and PageStyle components in the structure pane for pageno.rod. Then right-click on the PageNoDisplay label, and choose Properties to open the Component Editor.

The label's ObjectVariable property has been set to PageNoDisplay, which is the name of the component itself. This setting allows objects or code in other areas of the report to access the label control's value. The setting of ObjectVariable does not have to be the same as the name of the component to provide this accessibility. That it does happen to have the same name as the label control here is only a coincidence.

After Actuate generates all the pages, it goes back through the report page by page, and adds the page numbers in relation to the total number of pages.

The code in the report component's overridden Finish() method uses a number of AcPage methods:

•	GetPage( ) returns the first page of the report.

•	GetPageList( ) returns a list of all the pages contained within this report.

•	GetPageCount ( ) counts the number of pages in the list returned by GetPageList( ).

•	GetPageIndex( ) gets the page number of the page.

It also uses some methods from the AcIterator class to locate objects within the report:

•	SkipForwardTo( ) looks through the report until it finds a specified location.

•	HasMore( ) checks to see whether there are more pages to look through.

•	GetNext( ) gets the next page.

Sub Finish( )

Dim curPage As PageNoExampleApp::PageNoExamplePage

Dim curPageNum As Integer

Dim iter As AcIterator

Set curPage = GetPage( )

curPageNum = 0

NumPages = 1 + GetPageList().GetPageCount() - GetPage( ).GetPageIndex()

Set iter = GetPageList.Pages.NewIterator()

iter.SkipForwardTo( GetPage( ) )

Do While iter.HasMore( )

Set curPage = iter.GetNext( )

curPageNum = curPageNum + 1

curPage.PageNoDisplay.Text = "Page " & Str$(curPageNum) & " of " & + Str$(NumPages)

Loop

Super::Finish( )

End Sub


AcReport::GetContent method

Returns the top-most component in the report.

Syntax

Function GetContent( ) As AcReportComponent

Description

Returns the top-most component in the report.


AcReport::GetPageList method

Returns the list of pages in the report.

Syntax

Function GetPageList( ) As AcPageList

Description

Returns the list of pages in the report.


AcReport::GetTwipsPerPixel method

Sets the ratio of twips per pixel.

Syntax

Function GetTwipsPerPixel( ) As Integer

Description

Actuate sizes report components in twips (1/1440 of an inch). Web browsers size report objects, such as images, applets, and lines, in pixels.  When generating an HTML report, Actuate converts the twips in .ROD's or .ROI's into pixels for HTML.

A pixel can be many different sizes depending on factors such as screen size and resolution.  Actuate uses an approximation of 15 twips per pixel. When Actuate computes the pixel size of an object, it uses:

pixel size = twips size / twips-per-pixel

You can set the twips-per-pixel ratio by overriding GetTwipsPerPixel(  ).  Your GetTwipsPerPixel( ) method should return the new ratio.


AcReport::NewContent method

A generated method that creates the top-level section.

Syntax

Function NewContent( ) As AcReportComponent

Description

NewContent( ) is called by AcReport to create the top-level section as specified in the Design Editor.

Generally, you do not need to override NewContent( ).

Return value

A reference to the AcReportComponent object it creates.


AcReport::NewPageList method

See also

A generated method that creates the page list for the report.

Syntax

Function NewPageList( ) As AcPageList

Description

NewBook( ) is called by AcReport to create the page list for the report. Using the page list specified through the Design Editor, NewPageList( ) creates an instance of a subclass of AcPageList.

Generally, you do not need to override NewPageList( ). Instead, you use the Design Editor to specify the PageList class to use for the report. Alternatively, you can override NewPageList( ) to create the page list with a different page style. If you override this method, replace it. Do not call the superclass method.

Return value

A reference to the AcPageList object it creates.


See also

Class AcPageList


AcReport::OnFinishViewer method

See also

Called by the viewer before it closes the report instance (.ROI) file.

Syntax

Sub OnFinishViewer( )

Description

This method is called by the viewer before it closes the report instance (.ROI) file. You can override OnFinishViewer( ) to perform tasks at the completion of viewing; for example,

•	Close a DDE link or a file that you opened in OnStartViewer( ).

•	Count the number times a report is viewed.


See also

AcReport::OnStartViewer method


AcReport::OnStartViewer method

See also

Called by the viewer before it opens the report instance (.ROI) file.

Syntax

Sub OnStartViewer( )

Description

This method is called by the viewer before it opens the report instance (.ROI) file. You can override OnStartViewer( ) to perform tasks prior to viewing; for example, initialize a DDE link.


See also

AcReport::OnFinishViewer method


AcReport::Start method

Called at the start of the Factory.

Syntax

Sub Start( )

Description

Actuate calls Start( ) after the Factory has instantiated the report, but before report generation begins. Override Start( ) to add startup code, for example, to initialize global variables. Call Super::Start( ) before your custom code to ensure that the Factory executes the original code as well.


AcReport::SuggestRoiName method

Return the ROI name for this report.

Syntax

Function SuggestRoiName( ) As String

Description

SuggestRoiName( ) suggests the ROI name for this report.  By default, the ROI name is what is in the RoiFileName parameter.  Override this method to customize the ROI name. For example, override SuggestRoiName to generate a name based on parameters or the run date.

Return value

The name of the ROI.


Class AcReportComponent

See also   Methods

The base class for all sections, pages, frames, and controls.

Description

AcReportComponent is the base class for all sections, pages, frames, and controls. It establishes the core protocol for how objects in a report are created and how they fit together in the report's containment structure.

The Build methods are key language elements--they specify the logic for how the framework creates all the objects and their contents. Build( ) is always called from a container object.

At the topmost level of the structure, the Build( ) method for the report object creates the next level object, the report, and calls the Build( ) method for the report to create the report's contents. Each container object performs this task until all objects and their contents are built, as shown in the following figure.

Objects, except for controls, can contain one or more contents. AcReportComponent provides the means to identify containers and their lists of contents. References to all these objects are stored in a list object, which makes it easy for the framework or applications to traverse the containment structure. The following figure shows the container-content relationship between objects in the containment structure.

The framework maintains two lists to describe the two types of containment structures: content and page (display). The following figure shows examples of the two structures.

•	The content containment structure reflects the content hierarchy in the Design Editor. It shows the relationship between containers and content. For example, a group section is called for each of its frames.

•	The page containment shows which elements appear on each page. Note that only visual objects or objects having to do with visual organization appear here.

Use the AcIterator class to traverse the content list.

Note

Because AcReportComponent establishes the containment and build protocols, you should be careful when overriding the methods in this class or its derived classes.

Two-pass aggregates

AcReportComponent defines a core set of methods needed to support two-pass aggregates. These methods include HasAggregates( ) and IsTwoPass( ). Typically, only report and group sections compute two-pass aggregates. See AcDataSection for a full description.

Subclassing AcReportComponent

Because AcReportComponent is the foundation for all classes of persistent objects, you generally do not derive directly from AcReportComponent.

Variables

Variable	Type	Description
Container	AcReport Component	The object that contains the current object.
RowCount	Integer	Counts the number of rows which the section has processed. It is incremented at the start of the BuildFromRow( ) method. Do not reset this counter, it is used internally by the section.
TocEntry	String	The Table of Contents entry text
Properties

Property	Type	Description
TocValueExp	Expression	Returns a string to show as the Table of Contents entry for this object.
Methods

Method	Type	Description
AddContent( )	N/A	Adds a new content to the component.
Build( )	N/A	Overridden by container objects to build objects that do not use data rows.
BuildFromRow( )	AcBuildStatus	Overridden by data container objects to build objects that use data rows.
BuildTocList( )	N/A	Finds the TOC children and adds them to a list.
DetachContent( )	N/A	Detach a report component from its container component.
DetachFromContainer( )	N/A	Detach a report component from its container component.
Finish( )	N/A	Called when the object is finished building.
GetConnection( )	AcConnection	Returns the connection that is associated with this component.
GetContainer( )	AcReport	Returns a reference to the container object for this component.
GetContentCount( )	Integer	Returns the number of content items in a component.
GetContents( )	AcList	Returns a handle to the list of contents for this component.
GetContentIterator( )	AcIterator	Returns an iterator over the contents of this component.
GetDataStream( )	AcDataStream	Returns the data stream associated with this component.
GetFirstContent( )	AcReport Component	Gets the first content component.
GetFirstContentFrame	AcFrame	Gets the first content frame for a component.
GetPage( )	AcPage	A Viewer method that returns the page that a particular object first appears on.
GetPageIndex( )	Integer	A viewer method that returns the page number where an object is found.
GetPageList( )	AcList	Returns the page list associated with the report that contains this component.
GetReport( )	AcReport	Returns the report that contains this component.
GetRowCount( )	Integer	Returns the number of rows that this component has processed.
GetTocEntry( )	String	Returns the text of the TOC entry.
GetTocList( )	AcList	Returns the list of TOC children.
HasAggregates( )	Boolean	Returns True if this component itself needs to compute two-pass aggregates.
HasContents( )	Boolean	Returns True if this component has at least one content.
IsContainer( )	Boolean	Returns True if this component can have contents.
IsLeaf( )	Boolean	Returns True if this component cannot have contents.
IsTwoPass( )	Boolean	Returns True if this component, or its contents, needs to compute two-pass aggregates.
IsVisual( )	Boolean	Returns whether the component is visual.
OnRow( )	N/A	Called for each new row.
SetTocEntry( )	N/A	Generated. Sets the name of the table of content's entry
Start( )	N/A	Called when the component begins to be built.


See also

Class AcPageList

Class AcSection

Class AcVisualComponent


Methods for class AcReportComponent

AcReportComponent::AddContent method

AcReportComponent::Build method

AcReportComponent::BuildFromRow method

AcReportComponent::BuildTocList method

AcReportComponent::DetachContent method

AcReportComponent::DetachFromContainer method

AcReportComponent::Finish method

AcReportComponent::GetConnection method

AcReportComponent::GetContainer method

AcReportComponent::GetContentCount method

AcReportComponent::GetContents method

AcReportComponent::GetFirstContent method

AcReportComponent::GetFirstContentFrame method

AcReportComponent::GetContentIterator method

AcReportComponent::GetDataStream method

AcReportComponent::GetPage method

AcReportComponent::GetPageIndex method

AcReportComponent::GetPageList method

AcReportComponent::GetReport method

AcReportComponent::GetRowCount method

AcReportComponent::GetTocEntry method

AcReportComponent::GetTocList method

AcReportComponent::HasAggregates method

AcReportComponent::HasContents method

AcReportComponent::IsContainer method

AcReportComponent::IsLeaf method

AcReportComponent::IsTwoPass method

AcReportComponent::IsVisual method

AcReportComponent::OnRow method

AcReportComponent::SetTocEntry method

AcReportComponent::Start method


AcReportComponent::AddContent method

See also

Handles the standard steps for attaching a contained component to a report.

Syntax

Sub AddContent( component As AcVisualComponent )

component

The visual component to add to a container.

Description

The AddContent( ) method adds a new content to the component. This method raises an error if the component does not allow contents.


See also

AcReportComponent::GetContents method

AcReportComponent::GetContentIterator method

AcReportComponent::GetContainer method

AcReportComponent::IsContainer method

AcReportComponent::IsLeaf method


AcReportComponent::Build method

See also

Overridden by subclasses to build objects that do not use data rows.

Syntax

Sub Build( )

Description

Build( ) is called by container objects and is overridden by derived content classes to create their contents. A report, for example, overrides Build( ) to create all the pages in the report. Similarly, a frame overrides Build( ) to create all the controls it contains.


See also

AcReportComponent::BuildFromRow method


AcReportComponent::BuildFromRow method

See also

Overridden by derived classes to build objects that use data rows.

Syntax

Function BuildFromRow( row As AcDataRow ) As AcBuildStatus

row

A reference to the row used by the object.

Description

Like Build( ), BuildFromRow( ) is called by container and overridden by derived classes to create their contents. The difference is BuildFromRow( ) creates objects that use data rows.

Typically, frames override BuildFromRow( ) to create data controls, and controls override this method to set their values.

Return value

The build status: Continue Building or Finished Building.


See also

AcReportComponent::Build method


AcReportComponent::BuildTocList method

Add TOC entries to a child list.

Syntax

Sub BuildTocList( )

Description

Locates the TOC children and adds them to a list.


AcReportComponent::DetachContent method

Detaches a report component from its container component.

Syntax

Sub DetachContent( content As AcReportComponent )

content

The contained component to remove.

Description

Most components are contained within another component. This method lets the container component drop any of its contained components. For example, you might decide that for certain data rows you want to omit certain controls. This method does not delete the component; the component still resides in the persistent ROI file, but it no longer appears in the Viewer.


AcReportComponent::DetachFromContainer method

Detaches a report component from its container component.

Syntax

Sub DetachFromContainer( )

Description

Most report components keep track of the container component that contains the component. There are times when you might decide to remove an object from its container. For example, you may decide that for certain data rows you want to omit certain controls. This method does not delete the component; the component still resides in the persistent ROI file, but it no longer appears in the Viewer.


AcReportComponent::Finish method

See also

Contains the logic for completing an object.

Syntax

Sub Finish( )

Description

Finish( ) contains the logic for completing an object.

After Finish( ) has finished processing, the Persistent Object Storage Mechanism (POSM) writes the objects to the report instance (.ROI) file as needed. POSM optimizes memory usage by swapping objects in and out of memory.

Derived classes can override Finish( ) to do additional work when the Factory finishes processing the component. The derived version must always call the superclass version after doing the custom work.

About UnpinObject( )

UnpinObject( ) is an Actuate Basic function that works with POSM. UnpinObject( ) releases an object that was previously pinned to memory by PinObject( ).

Objects that are pinned to memory are not written to disk. Objects that hold references to transient objects need to be pinned so they are not written to disk, maintaining the reference to the transient object. When an object is finished and ready to be written to disk, Finish( ) calls UnpinObject( ) to release the object.

See AcBaseFrame::Finish method for an example showing how to use the Finish( ) method.


See also

AcReportComponent::Start method

AcBaseFrame::Finish method


AcReportComponent::GetConnection method

Returns the connection associated with this component.

Syntax

Function GetConnection( ) As AcConnection

Description

This method locates the connection by starting with the current component and looking upward through the containment hierarchy to find the first available connection. Sections can explicitly define a connection by placing the connection in the Connection slot, or implicitly by placing the connection inside the Connection slot of the data stream for that section. If a section does not have a connection available through one of these two means, then the framework continues searching with the next enclosing section until either a connection is found or until the search reaches the root of the report.

The framework uses this method to locate the connection to use for a data stream when you do not explicitly specify a connection. This allows you to create a sequential report that will print five subreports about your customer database. If you place the database connection on the topmost sequential section, then all the nested reports share this connection by using this method to search upward through the hierarchy to find the connection.

Return value

The connection associated with this component.


AcReportComponent::GetContainer method

Returns a reference to the container object for this component.

Syntax

Function GetContainer( ) As AcReportComponent

Description

The GetContainer method returns a reference to the container for this object, if any, for this component.

Return value

A reference to the container object for this component.

Nothing if this component does not have a container object.


AcReportComponent::GetContentCount method

Returns the number of content items in a component.

Syntax

Function GetContentCount( ) As Integer

Description

The GetContentCount method returns the number of content items in a component. For example, if the component is a section, GetContentCount returns the number of content components in the section, including any contained in the Before or After slots; if the component is a frame, GetContentCount returns the number of controls in the frame.

If a components does not have contents (for example, a control), GetContentCount returns 0.

Return value

An integer greater than 0 if the component has contents.

0 if the component does not have contents.


AcReportComponent::GetContents method

Returns a handle to the list of contents for this component.

Syntax

Function GetContents( ) As AcList

Description

The GetContents( ) method returns a handle to the list of contents, if any, for this component.

Return value

A handle to the list of contents for this component.

Nothing if this component does not support contents.


AcReportComponent::GetFirstContent method

Gets the first content component.

Syntax

Function GetFirstContent( ) As AcReportComponent

Description

The GetFirstContent( ) method looks for and returns the first content component of a report component, such as a section, frame or the AcReport component. You can then perform an action specifically on the first component.

All report components may have contents. The type of contents (controls, sections, etc.) depend upon the component type. If one or more content components exist, GetFirstContent( ) returns the first one.

Return value

The first Contents component.


AcReportComponent::GetFirstContentFrame method

Gets the first content frame (if any) for the current component.

Syntax

Function GetFirstContentFrame( ) As AcFrame

Description

The GetFirstContentFrame( ) method looks for and returns the first content frame (if any) for a component of a report, or Nothing if there is no content frame.

If the current object is a report or group section, GetFirstContentFrame( ) returns the first content frame in that object, skipping the Before frame.

Return value

The first Contents frame.

Nothing if there are no content frames.


AcReportComponent::GetContentIterator method

Returns an iterator over the contents of this component.

Syntax

Function GetContentIterator( ) As AcIterator

Description

The GetContentsIterator( ) method returns an iterator over the contents of this component. The returned value will never be Nothing. If the component cannot have contents, the default creates an iterator over an empty list. This allows clients to iterate over all components in a uniform manner.

Return value

An iterator over the contents of this component.


AcReportComponent::GetDataStream method

Returns the data stream that is associated with this component.

Syntax

Function GetDataStream( ) As AcDataStream

Description

This method locates the data stream by starting with the current component and looking upward in the containment hierarchy to find the first available data stream. The search stops when either it finds a section that has a data stream defined or when it reaches the root of the report.

You can use this method to make multiple passes over your data. For example, you might have a report of orders for a customer in which you want to both graph the orders and print them in detail. To do this, you would first create a grouped orders-by-customer report. Then, you could add a custom nested report that makes a second pass over the data to create the graph. If you do this, you must ensure that your data stream can be "rewound" by inserting a memory buffer filter. Also, be sure that your nested report leaves the data stream positioned at the same row as it was before the nested report started, or your outer report produces incorrect results.

Return value

The data stream associated with this component.


AcReportComponent::GetPage method

See also

A Viewer method that returns the page that a particular object first appears on.

Syntax

Function GetPage( ) As AcBaseFrame

Description

At run time, the Viewer calls GetPage( ) to get the page on which the object appears and then displays the page for an object that the user selects in the table of contents. You can also use GetPage( ) to get the page for a structural object, such as a section. However, since a section is nonvisual, GetPage( ) gets the page that shows the header for that section.

If you want just the number of the page that an object is on, use GetPageIndex( ).

Return value

The page on which an object first appears.


See also

AcReportComponent::GetPageIndex method


AcReportComponent::GetPageIndex method

See also

A Viewer method that returns the number of the page that an object is on.

Syntax

Function GetPageIndex( ) As Integer

Description

GetPageIndex( ) returns the page number in the report, starting with 1. If you want to get the page an object is on, use GetPage( ).

Return value

The number of the page the object is on.


See also

AcReportComponent::GetPage method


AcReportComponent::GetPageList method

Returns the page list associated with the report that contains this component.

Syntax

Function GetPageList( ) As AcList

Description

Returns the page list associated with the report that contains this component. The framework uses this method whenever it wants to add a new frame to the page list. You can use this method to get the page list if you want to start a new page or add your own custom frame to the page list.

Return value

The page list associated with the report that contains this component.


AcReportComponent::GetReport method

Example

Returns the report that contains this component.

Syntax

Function GetReport( ) As AcReport

Description

Returns the report that contains this component.

You can use this method if you create variables on the report that you want to access elsewhere in your application. The procedure is:

1	Declare a variable of the type of your report.

2	Call this method to get the report and assign it to your variable.

3	Use that object reference variable to access your report variables.


Example

Dim rpt	As MyReport

Set rpt = GetReport ( )

BackgroundColor = rpt.NextColor

Return value

The report that contains this component.


AcReportComponent::GetRowCount method

Returns the number of rows that this component has processed.

Syntax

Function GetRowCount( ) As Integer

Description

Returns the number of rows that this component has processed. This number is useful if you override methods to do custom processing, and you need to know if the row is the first row or to get the number of rows your component has processed.

Return value

The number of rows this component has processed.


AcReportComponent::GetTocEntry method

Gets the text of the TOC entry.

Syntax

Function GetTocEntry( ) As String

Description

Returns the text of the TOC entry for this component.


AcReportComponent::GetTocList method

Gets the list of TOC children.

Syntax

Function GetTocList( ) As AcList

Description

Returns the list of TOC children.


AcReportComponent::HasAggregates method

See also

Returns True if this component itself needs to compute two-pass aggregates.

Syntax

Function HasAggregates( ) As Boolean

Description

The HasContents( ) method returns True if this component itself needs to compute two-pass aggregates.

Return value

True if this component needs to compute two-pass aggregates.

False if this component does not need to compute two-pass aggregates.


See also

AcDataSection::HasAggregates method


AcReportComponent::HasContents method

Returns whether the component has at least one content.

Syntax

Function HasContents( ) As Boolean

Description

The HasContents( ) method determines whether the component has at least one content.

Return value

True if the component has at least one content.

False if either the component cannot have contents or the list of contents is empty.


AcReportComponent::IsContainer method

See also

Determines whether a component can have contents.

Syntax

Function IsContainer( ) As Boolean

Description

The IsContainer( ) method determines whether a component can have contents. This method is the opposite of IsLeaf( ).

Return value

True if the component can have contents.

False if the component cannot have contents.


See also

AcReportComponent::IsLeaf method


AcReportComponent::IsLeaf method

See also

Determines whether a component cannot contain contents.

Syntax

Function IsLeaf( ) As Boolean

Description

The IsLeaf( ) method determines whether a component cannot have contents. This method is the opposite of IsContainer( ).

Return value

True if the component cannot have contents.

False if the component can have contents.


See also

AcReportComponent::IsContainer method


AcReportComponent::IsTwoPass method

See also

Returns whether this component needs to compute two-pass aggregates.

Syntax

Function IsTwoPass( ) As Boolean

Description

Returns whether this component needs to compute two-pass aggregates.

Return value

True if this component or its contents needs to compute two-pass aggregates.

False if this component or its contents does not need to compute two-pass aggregates.


See also

AcDataSection::IsTwoPass method


AcReportComponent::IsVisual method

Returns whether the component is a visual component.

Syntax

Function IsVisual( ) As Boolean

Description

Determines whether the component is a visual component.

Return value

True if the component is visual; that is, it appears on the screen.

False if the component is not a visual component.


AcReportComponent::OnRow method

Example

Called for each new row.

Syntax

Sub OnRow( )

Description

Called for each new row.


Example

The following example shows how to create a distinctive look for the sales reports of three sales offices within the same company. View the code used in this example in a fuller context by opening Examples\ CONDTNL.ROD, highlighting the group section component OfficeGroup, and examining its OnRow( ) method.

The following code sets a custom variable, ContentsFrame, in OfficeGroup. When the code is finished executing, the variable ContentsFrame will contain one of three possible frames, BostonFrame, NewYorkFrame, or PhiladelphiaFrame. The choice of the correct frame depends upon the value of the offices_officeID variable of the current row. For instance, if offices_officeID is 1, then the variable ContentsFrame will contain BostonFrame.

This example does not actually instantiate any frame as content for the OfficeGroup group section in CONDTNL.ROD -- it merely identifies which frame should be instantiated as content. The OfficeGroup component's NewContent( ) method determines the correct frame to instantiate by inspecting the ContentsFrame variable you set in the OnRow( ) method.

Sub OnRow( row As AcDataRow )

Dim currentRow As ConditionalExampleDataRow

Set currentRow = row

Select Case currentRow.offices_officeID

Case 1

Set ContentsFrame = New Persistent BostonFrame

Case 2

Set ContentsFrame = New Persistent NewYorkFrame

Case 3

Set ContentsFrame = New Persistent PhiladelphiaFrame

End Select

'Notice that the call to the super occurs here, at the end of the custom code

Super::OnRow( row )

End Sub


AcReportComponent::SetTocEntry method

A generated method that sets the text of a TOC entry.

Syntax

Sub SetTocEntry( )

Description

SetTocEntry( ) uses the TocValueExp property value to assign table of contents names.


AcReportComponent::Start method

See also

Contains the logic for preparing an object for the build process.

Syntax

Sub Start( )

Description

Start( ) calls PinObject( ) and prepares an object for the build process.

Derived classes can override Start( ) to do additional work when the Factory starts processing the component. The derived version must always call the superclass version before doing the custom work.

About PinObject( )

PinObject( ) is an Actuate Basic function that works with the Persistent Object Storage Mechanism (POSM). POSM writes persistent objects to the report instance (.ROI) file. It also optimizes memory usage by swapping objects in and out of memory as needed.

PinObject( ) pins an object to memory so that it is not written to disk. Objects that hold references to transient objects need to be pinned so that they maintain their references to the transient object.


See also

AcReportComponent::Finish method


Class AcReportController

Methods

Issues Viewer commands to a report.

Description

AcReportController lets you issue Viewer commands to a report from Basic code in the Viewer. The report can be the same one issuing the commands, or it can be some other report. You can also use the ReportController class to navigate between pages or to implement hyperlinks.

Hyperlinks connect one visual object, typically a data control, in a report to another object in either the same report or another report. Create hyperlinks to let users access related or detailed information on another page or in another report. For example, users may find it useful to jump from a customer record to that customer's order record, or from a summary report to a detailed report.

To use this class, first create an instance of this class, then call either AttachToThisReport( ) or AttachReport( ).

Methods

Method	Type	Description
AttachToThisReport( )	Boolean	Establishes a link to the current report.
AttachReport( )	Boolean	Establishes a link to another report.
FollowLink( )	Boolean	Locates an object for a hyperlink.
ShowNextPage( )	N/A	Displays the next page.
ShowPage( )	N/A	Displays the specified page.
ShowPrevPage( )	N/A	Displays the previous page.


Methods for class AcReportController

AcReportController::AttachToThisReport method

AcReportController::AttachReport method

AcReportController::FollowLink method

AcReportController::ShowNextPage method

AcReportController::ShowPage method

AcReportController::ShowPrevPage method


AcReportController::AttachToThisReport method

Attaches the report controller to the current report.

Syntax

Function AttachToThisReport( ) As Boolean

Description

Establishes a link to the current report. You can then issue Viewer commands to control the report.

Return value

True if successful.

False if an error occurs.


AcReportController::AttachReport method

Attaches the report controller to the specified report.

Syntax

Function AttachReport( fileName As String) As Boolean

fileName

The name of the external report (.ROI file) to which to attach.

Description

Establishes a link to an external report. If the report is not yet open in the Viewer, this call opens it.

Return value

True if the report is successfully opened.

False if an error occurs. The most likely error is that the .ROI file does not exist.


AcReportController::FollowLink method

Executes a link to the destination component.

Syntax

Function FollowLink( className As String, variableName As String, valueString As String, newView As Boolean ) As Boolean

className

The class name of the component to link to.

variableName

The component variable to search for in the class being searched. If you want to search a data control, this name will be Data Value.

valueString

The variable value to search for. This variable can contain wildcard characters. The wildcards are the same as those you use in the Viewer's search window.

newView

True means to show a new view. False means to use the current view. If the destination is another report, and that report is not open, it will be opened automatically. Subsequent calls to FollowLink( ) will use this view.

Description

The FollowLink( ) method establishes and executes (navigates) the link between objects in reports. A report, either internal or external, must have been attached. FollowLink searches through the report until the first occurrence of the specified link is located.

The search string can contain the following wildcard characters:

Pattern	Description
\	Escape next character (one- or two-byte character)
?	Match any one character (one- or two-byte character)
#	Match any ASCII numeric character [0-9]
*	Match zero or any number of characters
\a	Match one alarm (0x07)
\b	Match one backspace character (0x08)
\t	Match one tab character (0x09)
\n	Match one new line (0x0A)
\f	Match one form feed (0x0C)
\r	Match one carriage return (0x0D)
\\	Match one backslash character (\)
[]	Match zero characters (ignored)
[char-list]	Match any one character inside the brackets
[a-z0-9]	Match any lowercase or ASCII numeric character (character code range always)
[a-z-]	Match any lowercase character or hyphen
[^a-z0-9]	Match any character other than lowercase or ASCII numeric
[^]	Matches one caret (^)
[?] or \?	Match one question mark (?)
[\3] or \#	Match one pound sign (#)
[*] or \*	Match one asterisk (*)
[[] or \[	Match one open-square-bracket ([)
[]] or \]	Match one close-square-bracket (])
[\[-\]]	Match any ASCII character whose code is between [ and ]
[\1-\377]	March any one-byte character excluding NULL (0x00)
[\x100-\xffff]	Match any two-byte character


AcReportController::ShowNextPage method

Displays the next page.

Syntax

Sub ShowNextPage( )

Description

Displays the page following the current page. If the current page is the last page, ShowNextPage stays on the current page.


AcReportController::ShowPage method

Displays the specified page.

Syntax

Sub ShowPage( pageNumber As Integer)

pageNumber

The ordinal number of the page.

Description

Displays the page specified by pageNumber. If pageNumber is out of the valid range of pages, ShowPage stays on the current page.


AcReportController::ShowPrevPage method

Displays the previous page.

Syntax

Sub ShowPrevPage( )

Description

Displays the page previous to the current page. If the current page is the first page, ShowPrevPage stays on the first page.


Class AcReportSection

Example   Methods

A class that builds a report from a data stream.

Description

The report section class builds a report from rows read from a data stream. The report section is a kind of data section, and so it provides a Before and After frame, contents, and a page header and footer. The report section inherits a connection slot from AcSection, and adds the slot to the specified data stream.

Factory protocol

The following table shows how a report section works in the Factory.

Task	Method
1 Initializes the section.	New( )
2 Prepares the report section for Factory processing. Start( ) instantiates and opens the connection, if any, and instantiates the data stream.	Start( )
3 Opens the data stream, builds the report by reading each row from the data stream, then processes it as described for AcDataSection.	Build( )
4 Similar to Build( ), but gives you the ability to create a nested report as described below.	BuildFromRow( )
5 Closes the data stream and connection.	Finish( )
Working with data streams and connections

The report section centers on a data stream. Many data streams need a connection. The report section gives you many options for assembling these components. This section explains a few of these options.

Connection

Typically when you create a report section, you usually place the connection to the connection slot of the data stream itself. However, if you want to share the connection with nested sections, you should place the connection in the Connection slot of the report section. See the GetConnection( ) method for details.

If you place the connection in the Connection slot of the report section, the report will open the connection in Start( ) method of the report section. If you want to share a connection defined in a section that appears above this report in the containment hierarchy, leave both the report section and data stream Connection slots empty; the framework automatically searches to find the shared connection. As described in AcSection, you can customize how the report obtains and opens the connection. See AcSection::ObtainConnection( ) for details.

Data stream

A report should contain a data adapter component in the Data Stream slot. It is not an error for a report to have no data stream; it will still output the Before and After components, but it produces no data rows.

By default, the report instantiates and opens the data adapter that appears in the Data Stream slot. However, if you want to customize this behavior, you can override ObtainDataStream( ) to take control of this process. Be sure your override returns an instantiated, started data adapter. If you override ObtainDataStream( ), you may want to also override FinishDataStream( ) to prevent the report from closing the data stream if your data stream is shared with other report sections.

The data stream life cycle is shown in the following table:

Protocol Method	Calls...	To...
Start( )	AcSection:: ObtainConnection( )	Create or locate the connection for this report.
	AcReportSection:: ObtainDataStream( )	Create or locate the data stream for this report. By default, this method calls NewDataStream( ) to instantiate the data stream.
	AcReportSection:: NewDataStream( )	Instantiate the data stream. By default, this method instantiates the data adapter specified in the Data Stream slot in the structure pane.
	AcReportComponent ::GetConnection( )	By default, called by ObtainDataStream( ) to locate the connection to associate with the data stream.
Build( )	AcReportSection:: StartDataStream( )	Start the data stream, if any, returned by ObtainDataStream( ).
	AcDataAdapter:: Fetch( )	Fetch each row from the data stream.
Finish( )	AcReportSection:: FinishDataStream( )	Finish processing the data stream, if any. By default, closes the data stream.
	AcSection:: FinishConnection( )	Finish processing the connection, if any. By default, closes the connection.
You can override any of the methods in the middle column to customize your section or data adapter to suit your application.

Nested reports

You will sometimes want to create one report that nests inside another. For example, suppose you have an Access database that lists the customers for which you are responsible. You want to create a report that, for each of these customers, creates a list of the open orders for that customer. The orders reside in the departmental Oracle database. In this case,

1	Create a top report to query your Access database.

2	In the Content slot of the outer report, create another report to query the orders you want to retrieve and print.

The inner report section opens its data stream at the beginning of its Build( ) method. To set a parameter on the inner query based on a value in the current data row in the outer query, override the BuildFromRow( ) method to get the customer ID from the outer data row, then pass this value to the query you created in your inner report.


Example

These examples show how to build nested reports.

Sub BuildFromRow( row As AcDataRow) As Boolean

     Dim cust        As CustomerRow

     Dim orders    As OrdersQuery

     'Get the customer row

     Set cust = row

     'Get the (unopened) data stream for this report

     Set orders = GetDataStream( )

     'Tell the data stream which customer to use when

     'parameterizing the query.

     orders.CustID = row.CustID

     'Let the super class method do the actual building

     BuildFromRow = Super::BuildFromRow( row )

End Sub

Occasionally, you might want to parameterize a connection as well as a query for a nested report. For example, you might have five department databases, each with the same schema, but with different names. You want to run an outer query that lists the server for each department, then an inner report that queries some data on that server. The report normally opens its connection in the Start( ) method. For this example, you need to write custom code that will postpone opening the connection until your code reaches a call to the BuildFromRow( ) method. To do so, you have to override two methods: ObtainConnection( ) and BuildFromRow( ). You can let the report section close the connection in the usual way.

Function ObtainConnection( ) As AcConnection

     'Instantiate, but don't open, the connection

     Set ObtainConnection = NewConnection( )

End Function

Function BuildFromRow( row As AcDataRow ) As Boolean

     Dim server            As ServerRow

     Dim deptConn      As DepartmentConnection

     'Get the data row

     Set server = row

     'Get the connection

     Set deptConn = GetConnection( )

     'Parameterize and open the connection.

     deptConn.ServerName = server.ServerName

     Verify( deptConn.Connect( ) )

     'Let the super class method do the actual building

     BuildFromRow = Super::BuildFromRow( row )

End Function

Properties

Property	Type	Description
DataStream	AcDataAdapter	The data stream that provides rows for this report.
Sorting	AcSortingOptions	Determine whether or not the report section puts a sort filter in front of the data source in a particular report section.
Methods

Method	Type	Description
Build( )	N/A	Builds the contents of the report.
BuildFromRow( )	AcBuildStatus	Builds a nested report optionally parameterized from a data row.
Finish( )	N/A	Finishes the report.
FinishDataStream( )	N/A	Closes the data stream for this report.
NewDataStream( )	AcDataAdapter	Instantiates the data stream for this report.
ObtainDataStream( )	AcDataAdapter	Creates or locates the data stream to use for this report.
SetSortKey	N/A	Sets the sort key for the data adapter for this report.
Start( )	N/A	Starts the report.
StartDataStream( )	N/A	Opens the data stream for this report.
Sorting

The Sorting property indicates whether a report section should perform automatic sorting for the data source it uses. The types of sorting available are:

•	AutoSort: The default. If AutoSort is set, the report section determines if the data source can sort data dynamically according to AddSortKey() calls.  If the data source cannot sort dynamically, the report section instantiates a sort filter and places that filter in the chain of data adapters.  The report section determines whether or not the data source yields data in the order expected by the group sections.

•	PreSorted. If PreSorted is set, the data arrives from the data source already sorted in the order that data sections expect the data.  No attempt is made to tell the data source how to sort (by making AddSortKey() calls), and the report section does not instantiate a sort filter.

•	CompatibleSort. CompatiableSort provides backwards compatibility with the AutoSort property of previous Actuate releases. AutoSort was set to True to indicate that the data source can sort dynamically. If this is the case, Sorting is set to CompatibleSort. Compatible sort means that the report section makes the AddSortKey() calls, but does not invoke a sort filter. If the old AutoSort property is set to False, the Sorting property is set to PreSorted.


Methods for class AcReportSection

AcReportSection::Build method

AcReportSection::BuildFromRow method

AcReportSection::Finish method

AcReportSection::FinishDataStream method

AcReportSection::NewDataStream method

AcReportSection::ObtainDataStream method

AcReportSection::SetSortKey method

AcReportSection::Start method

AcReportSection::StartDataStream method


AcReportSection::Build method

Builds the report.

Syntax

Sub Build( )

Description

The Build( ) method builds the report using the following sequence:

1	Starts the data stream by calling StartDataStream( ).

2	Produces the Page Header and Before components as described in AcDataSection.

3	Reads a row from the data stream by calling its Fetch( ) method. If there is no row, this method skips to step 9.

4	If there is no current content, then Build( ) calls NewContent( ) to create one.

5	Passes the row to the content's BuildFromRow( ) method. If the content accepts the row, then loops back to step 3.

6	Finishes the current content and instantiates a new one by calling NewContent( ).

7	Calls the content's BuildFromRow( ) method. This time, the content must accept the row.

8	Loops back to step 3.

9	Produces the After and Page Footer components as described in AcDataSection.

Build( ) is called for all reports except a parallel report. A parallel report calls BuildIntoFlow( ), not Build( ). If you override Build( ) for a parallel report, it will never be called.


AcReportSection::BuildFromRow method

Builds the report.

Syntax

Function BuildFromRow( row As AcDataRow ) As AcBuildStatus

Description

By default, the BuildFromRow( ) method calls Build( ). You might want to override BuildFromRow( ) to add parameters to your query. Use the parameters to retrieve only entries for a particular customer.

Return value

The status of the build.


AcReportSection::Finish method

Finishes the report.

Syntax

Sub Finish( )

Description

Finishes the report by closing the data stream and the connection. See AcBaseFrame::Finish method for an example showing how to use the Finish( ) method.

See also

AcBaseFrame::Finish method


AcReportSection::FinishDataStream method

See also

Closes the data stream for this report.

Syntax

Sub FinishDataStream( )

Description

Finishes the data stream. By default, it closes the data stream by calling its Finish( ) method. You can override this to, for example, do nothing if you want to use the same data stream instance later.


See also

AcReportSection::NewDataStream method

AcReportSection::ObtainDataStream method

AcReportSection::StartDataStream method


AcReportSection::NewDataStream method

See also

Instantiates the data stream.

Syntax

Function NewDataStream( ) As AcDataAdapter

Description

The NewDataStream( ) method instantiates the component placed in the DataStream slot of the report section. The data stream component is transient. If you override this method, use the New keyword, not New Persistent.

Return value

The data adapter that was instantiated.


See also

AcReportSection::FinishDataStream method

AcReportSection::ObtainDataStream method

AcReportSection::StartDataStream method


AcReportSection::ObtainDataStream method

See also

Creates or locates the data stream to use for this report.

Syntax

Function ObtainDataStream( ) As AcDataAdapter

Description

This method obtains the data stream that the report is to use. By default, it instantiates the data adapter that you placed in the Data Stream slot. You can override this method to use, for example, an existing data stream that you created elsewhere.

This method does not also open the data stream; use the StartDataStream( ) method instead.


Example

The following example shows how to query a database once, and use the result set for more than one report or subreport. To view the code used in this example in a fuller context, open Examples\smdsrc.rod. The example shows how a number of related methods work together in an Actuate report, in particular the ObtainDataStream, StartDataStream, and FinishDataStream methods.

The report design in smdsrc.rod has a sequential section with two subreports, R1 and R2. R1 and R2 use data from the same database query.  So instead of each subreport making its own individual query, R1 first makes the query for both, stores the resulting datastream in BufDStream, and uses it. Then R2 picks up the datastream from BufDStream and reuses it.

In report component R1, override the Finish method as follows:

Sub Finish( )

' At this point, we need to be sure to keep the datastream open.

' First instantiate sApp::BufDStream.

'Note:  BufDStream is a static variable of the sApp object.

'It is of type MemoryBuffer.  Here, we prepare the variable

'to provide the datasource for R2 later.

Set sApp::BufDStream = DataSource

'Rewind sApp::BufDStream now, so that when R2 uses it

'later, R2 will start from the first row of the buffer

sApp::BufDStream.Rewind()

Super::Finish( )

End Sub

To see BufDStream, open the component editor on the sApp component, and choose the Variables tab. BufDStream is what holds the data for R2.

In report component R2, override the ObtainDataStream, StartDataStream, and FinishDataStream methods. The call to Super::ObtainDataStream( ) has been deleted in the following code, so that the overridden methods do not inherit the original ObtainDataStream( ) behavior.

Function ObtainDataStream( ) As AcDataAdapter

' R2 will use sApp::BufDStream as its datastream.

Set ObtainDataStream = sApp::BufDStream

End Function

The call to Super::StartDataStream( ) has been removed in the following code so that the method does not inherit the superclass's StartDataStream( ) behavior. The method essentially does nothing.

Sub StartDataStream( stream As AcDataAdapter )

' We do not need to start the datastream since we are

    ' using sApp::BufDStream as R2's datastream.

End Sub

The following code does some cleanup.

Sub FinishDataStream( stream As AcDataAdapter )

    Super::FinishDataStream( stream )

' Since we no longer need sApp::BufDStream, set it

'to nothing.

Set sApp::BufDStream = Nothing

End Sub

Return value

The data adapter.


See also

AcReportSection::FinishDataStream method

AcReportSection::NewDataStream method

AcReportSection::StartDataStream method


AcReportSection::SetSortKey method

Sets the sort key for the data adapter.

Syntax

Sub SetSortKey ( adapter As AcDataAdapter )

adapter

The data adapter that supplies the data rows.

Description

The SetSortKey( ) method sorts the data rows by the keys specified in the data adapter. For example, you could have the data adapter first sort by customer ID, then by order number, and finally by line number. By default, this method sets the sort key to the columns you specified in the Key properties for any group sections in this report.

SetSortKey( ) is generated by the AFC framework based on the keys that you specified in the group sections to create a default layout. You can override SetSortKey( ) to provide additional processing.


AcReportSection::Start method

Performs tasks to start the report section.

Syntax

Sub Start( )

Description

The Start( ) method prepares the report section for processing each row. It

•	Instantiates and opens the connection, if any. (Done by AcSection::Start( ). )

•	Obtains the data adapter by calling ObtainDataStream( ).

•	Sets the sort key by calling SetSortKey( )


AcReportSection::StartDataStream method

See also

Opens the data stream for this report.

Syntax

Sub StartDataStream( stream As AcDataAdapter )

stream

The data stream to use for this report.

Description

This method prepares the data stream for reading. By default, it opens the data stream by calling its Start( ) method. You can override this method to, for example, do nothing if the data stream already exists and is open.


See also

AcReportSection::FinishDataStream method

AcReportSection::NewDataStream method

AcReportSection::ObtainDataStream method


Class AcReportView

Example   Methods

Provides a visual view of a report object.

Description

The report view class provides a way to visually examine a report object. There can be many views for the same object open at one time.

Use AcReportView methods to send a message to the window telling it to print the displayed report, or to examine the set of report components which a user has selected.

To examine (or scan through) the collection of report objects selected by a user:

1	Initialize the scan by calling StartSelectionScan( ).

2	Retrieve the number of objects in the collection by calling GetSelectionCount( ).

3	Iterate through the collection using GetNextSelection( ).

4	When you're finished with the scan, call EndSelectionScan( ) to close the collection and end the scan.

Methods

Method	Type	Description
EndSelection Scan( )	N/A	Ends the selection set scan.
GetNextSelection( )	AcReport Component	Retrieves an item in the selection set.
GetSelectionCount( )	Integer	Retrieves the number of objects in the selection set.
PrintAllPages( )	N/A	Allows a report to print all its pages.
PrintPages( )	N/A	Allows a report to print itself, with print options.
StartSelectionScan( )	N/A	Initialize the selection set scan. Call this method before calling the other selection set methods, or to re-set a selection set scan.


Example

The following example shows how to override the OnLButtonDown method to create a new control called "Extract", which copies the data values for the selected controls to a file. The method creates an AcReportView container, view, to hold the report object collection.

Function OnLButtonDown( view As AcReportView, Shift As AcShiftKeyState, x As Integer, y As Integer ) As Boolean
Dim outFile As Integer
Dim selCount As Integer
Dim i As Integer
Dim component As AcReportComponent
Dim control As AcDataControl

' This method shows how to do the export using a control as
' a button.  Note: DON'T call the Super:: method, it will
' clear the very selection you want to grab!

outFile = FreeFile( )
Open "export.txt" For Output As #outFile

' 1. Initialize the scan
view.StartSelectionScan( )

' 2. Get the number of objects in the collection
selCount = view.GetSelectionCount( )

'3. Iterate through the collection. If it's a control, save it to
' a file.
For i = 1 to selCount
Set component = view.GetNextSelection( )
If IsKindOf( component, "AcDataControl" ) Then
Set control = component
Print #outFile, control.GetValue( )
End If
Next

'4. You've examined the entire collection, so end the scan, and
' close the file.
view.EndSelectionScan( )
Close #outFile

End Function


Methods for class AcReportView

AcReportView::EndSelectionScan

AcReportView::GetNextSelection

AcReportView::GetSelectionCount

AcReportView::PrintAllPages

AcReportView::PrintPages

AcReportView::StartSelectionScan


AcReportView::EndSelectionScan

See also

Ends the selection set scan.

Syntax

Sub EndSelectionScan( )

Description

EndSelectionScan( ) ends the examination of the collection of report objects that the user selected. Call this method when you're finished examining the reports objects collection.


See also

AcReportView::GetNextSelection

AcReportView::GetSelectionCount

AcReportView::StartSelectionScan


AcReportView::GetNextSelection

See also

Retrieves the next object in the collection

Syntax

GetNextSelection( ) As AcReportComponent

Description

GetNextSelection( ) retrieves the next report object in the selected collection.Call this method to iterate through the collection.


See also

AcReportView::EndSelectionScan

AcReportView::GetSelectionCount

AcReportView::StartSelectionScan


AcReportView::GetSelectionCount

See also

Retrieves the number of report objects in the selected collection.

Syntax

GetSelectionCount( ) As Integer

Description

GetSelectionCount( ) retrieves the number of report objects in the selected collection. Use this number to iterate through the collection.


See also

AcReportView::EndSelectionScan

AcReportView::GetNextSelection

AcReportView::StartSelectionScan


AcReportView::PrintAllPages

See also

Prints all pages of a displayed report.

Syntax

Sub PrintAllPages( )

Description

PrintAllPages( ) allows users to print all pages of a report directly from the viewer window.


See also

AcReportView::PrintPages


AcReportView::PrintPages

See also

Prints a report directly from a viewer window.

Syntax

Sub PrintPages (silent As Boolean, first As Integer, last As Integer)

silent

TRUE to display the Print dialog box, FALSE otherwise.

first

The first page of a range of pages to print, or 0 to print the entire report.

last

The last page of a range of pages to print, or 0 to print the entire report.

Description

PrintPages( ) allows users to print reports directly from the viewer window, and provides a facility for automatic report printing.

If silent is FALSE, PrintPages displays the standard print dialog box, which allows users to set up print options for the report.

If silent is TRUE, the print dialog does not display and automatic report printing is enabled. This is useful for applications which run a series of reports, display them in the viewer, then print them and go on to the next in the series.

If first or last are set to integers greater than 0, only those pages print.


See also

AcReportView::PrintAllPages


AcReportView::StartSelectionScan

See also

Initialize the scan of the selected collection of report objects.

Syntax

StartSelectionScan( )

Description

StartSelectionScan( ) starts the scan of a selected collection of report objects. Use it to initialize your examination of a collection of report objects, or to re-set the scan.


See also

AcReportView::EndSelectionScan

AcReportView::GetNextSelection

AcReportView::GetSelectionCount


Class AcSection

Methods

The base class for all sections.

Description

A section is a structural component that builds the logical structure of the report. That is, when you look at the report design in the layout pane of the Design Editor, or run the report and view it, you don't see the sections themselves. The only visible sign of a section's existence in a report is the effect it has on the organization of the visual components, such as frames and controls. In the Design Editor, sections appear in the structure pane.

A section has high-level control of the overall design of the report. It defines the framework of the report by determining when a data stream will be opened, what kind of processing will be perform based on the rows in the data stream, and how and when frames are created.

Sections are persistent: they are written to the .ROI file. However, they are not visual in the Viewer. They exist "behind the scenes" to organize data and are used primarily for searching for data.

Types of sections

AcSection is the base class from which the Actuate framework sections are derived. Each type of section is summarized here. Further information about each type of section is described in more detail in the individual class descriptions.

Section type	Description	Example
Report	Produces a series of frames from rows obtained from a data stream. Provides slots to create a connection and data stream. Contents are usually group sections, frames, or nested report sections.	Print a list of customers from a query against an ODBC database.
Group	Groups data on a common field, such as customers grouped by state.	Print orders for customers in various states.
Sequential	Contains several frames, graphs, subreports, or sections that appear in a specified order.	Print two related reports, such as a sales history and a staffing history, one after the other.
Conditional	Uses a conditional expression to determine which of several frames, graphs, subreports, or sections to include in the report.	Print different frame for salaried, hourly, or commission employees.
Parallel	Contains two or more subreports that are displayed or printed simultaneously in different flows on the same page.	Present two related reports, such as employee addresses and salary histories, printed side by side for easy comparison.
Factory protocol

AcSection provides a specific protocol to be followed by derived classes. This protocol follows that set by AcReportComponent. The description here identifies the specific ways this class uses the standard protocol.

Method	Task
New( )	Initialize the section.
Start( )	Prepare the section for Factory processing
Build( )	Builds the contents of the section. Called for the topmost section in a report, and when no data row is available.
BuildFromRow( )	Build the contents of the section when a data row is available. Called for sections nested inside a report or group section.
Finish( )	Finish Factory processing.
The database connection

The standard way to work with database connections is to create the connection directly inside a data stream. This works fine if your report has just one data stream, or if each data stream in your report uses a different connection, or needs no connection at all. However, this scheme is inefficient if your report has multiple data streams that work with the same connection, and that connection is capable of processing multiple queries. In this case, it is more efficient to open the connection once, and then use it for multiple data streams. You do so by attaching the connection to a section instead of a data stream.

To determine which section to attach your connection, look in the structure pane of the Design Editor. Find the section that is the common parent of all the data streams that need that connection. This will often be the topmost section of your report. Then, move your connection into that slot from the Connection slot of the data stream.

The section instantiates and opens the connection in its Start( ) method and closes the connection in its Finish( ) method. All nested sections call GetConnection( ) to search for this connection up the containment hierarchy. The connection is valid as long as its section is active.

Some reports mix connections. For example, in creating a sales report, most queries might work against the Oracle sales database, but you might have one or two that work against a departmental Access database. In this case, you can connect to the Oracle database in your topmost section, then, in the query that works with your Access database, create an ODBC connection specifically for that query. When looking for the connection, the local connection takes precedence over any connection defined higher in the containment hierarchy.

If you want to keep two connections open, then you have to write custom code to maintain the second connection. In the above example, you can define a static variable to hold the connection, override the Start( ) method of your topmost section to open the additional ODBC connection, and override the Finish( ) method to close it. In the section where you need the second connection, override ObtainConnection( ) to return this second connection from the static variable you defined above, and override FinishConnection( ) to do nothing so that the nested section does not close this shared connection.

Interrupting a section

Sections usually run until they have processed all the available data rows or section contents. There are times when you might want to stop processing early. For example, you might want to stop output after the first page or after a certain number of rows. The section class gives you three methods to stop processing. They differ in the amount of cleanup they perform.

•	StopAfterCurrentRow( ) processes the current data row to completion before stopping. The section outputs the frame(s), if any, for the row and outputs totals, and so on, depending on the kind of frame. You use this method when you want to stop processing a section after a given row or a given number of rows. The resulting report will look as if the input data stream contained only rows up to the current row; all subsequent rows are silently ignored.

•	StopAfterCurrentFrame( ) finishes the current frame by placing it on a page, but then produces no more output. The section will not display any totals. Note that finishing the frame might entail creating a new page to contain the frame.

•	StopNow( ) stops the section; it discards any partially completed frames or partially processed data rows. Use this when you want to stop output at the end of a page. Do not create aggregates if you use this method because the aggregates will be incorrect.

Variables

Variable	Type	Description
ContentList	AcList	Contains the list of content component instances created for this section.
Properties

Property	Type	Description
PageBreakAfter	Boolean Function	True if the following section or frame should start at the top of a new page.
PageBreakBefore	Boolean Function	True if the Factory should start a new page before starting this section. That is, True if this section should appear at the top of a new page.
Subpage	AcSubpage	The optional subpage to use with the parallel report. If there is no subpage, then the parallel report assumes that the flows are available on the page itself.
Connection	AcConnection Structure Reference	The connection, if any, to instantiate for this section.
Methods

Method	Type	Description
AddContent( )	N/A	Adds content to a section.
CommittedToFlow( )	N/A	Called by the page list for each registered section.
DisableSubPage( )	N/A	Disables using subpages for the section.
EnableSubPage( )	N/A	Enables using subpages for the section.
FinishConnection( )	N/A	Closes the connection, if any, for this section. Override this if you don't want the section to close the connection.
FinishFlow( )	N/A	Called at the end of each flow.
FinishPage( )	N/A	Tells a section that a new page is finishing.
GetContents( )	AcList	Returns the list of contents for this section. (See AcReportComponent for details.)
GetCurrentRow( )	AcDataRow	Returns the current data row.
NewConnection( )	AcConnection	Instantiates the connection for this section.
ObtainConnection( )	AcConnection	Creates a connection for this section. Override this if you want to use other than the default mechanism to get a connection.
NewPage( )	AcPage	Lets the section determine the page on which it appears.
NewSubPage( )	AcSubPage	Instantiates a new subpage for the section.
PageBreakAfter( )	Boolean	Returns True if the PageBreakAfter property is set.
PageBreakBefore( )	Boolean	Returns True if the PageBreakBefore property is set.
StartFlow( )	N/A	Called at the beginning of each flow.
StartPage( )	N/A	Called at the start of each new page.
StopAfterCurrentFrame( )	N/A	Stop processing after the current frame is added to the page.
StopAfterCurrentRow( )	N/A	Stop processing after the current data row is complete.
StopNow( )	N/A	Stop processing a data row immediately.
Considerations for HTML reports

HTML documents are all one long page.  HTML does not support the concept of page breaks.  Therefore, properties that control pagination in Actuate reports are ignored when generating HTML for a report.  For this class, the specific properties ignored by HTML reports are:

•	PageBreakBefore

•	PageBreakAfter


Methods for class AcSection

AcSection::AddContent method

AcSection::CommittedToFlow method

AcSection::DisableSubPage method

AcSection::EnableSubPage method

AcSection::FinishConnection method

AcSection::FinishFlow method

AcSection::FinishPage method

AcSection::GetContents method

AcSection::GetCurrentRow method

AcSection::NewConnection method

AcSection::NewPage method

AcSection::NewSubPage method

AcSection::ObtainConnection method

AcSection::PageBreakAfter method

AcSection::PageBreakBefore method

AcSection::StartFlow method

AcSection::StartPage method

AcSection::StopAfterCurrentFrame method

AcSection::StopAfterCurrentRow method

AcSection::StopNow method


AcSection::AddContent method

Adds content to a section.

Syntax

Sub AddContent( content As AcReportComponent )

content

The element to which you are adding content.

Description

The AddContent( ) method adds content to a section. The component is appended to the end of the content list.

Typically, AddContent is automatically called. However, if you are creating your own custom section, you can call this method to add your custom contents.


AcSection::CommittedToFlow method

Called by the page list for each registered section.

Syntax

Sub CommittedToFlow( flow As AcFlow )

flow

The flow to which the section is committed.

Description

The page list calls the CommittedToFlow( ) method for each registered section when the page list has determined that the section is "committed" to the flow. That is, the flow contains at least one content frame from this section (or one of its contents) that is not a page decoration, and there is no longer the possibility that the decoration may be removed and restarted on another flow.

Note that there will be at least one call to StartFlow( ) before a call to CommittedToFlow( ), but there may be two calls; the first of which represents a failed attempt to start the section on an existing flow.


AcSection::DisableSubPage method

Disables using subpages for the section.

Syntax

Sub DisableSubpage( )

Description

Disables using subpages for the section. The predefined section classes automatically call this method. After this call, no subpages appear in the page, even if the Subpage property is set for this section.

Sections derived directly from AcSection start with their subpages disabled. The derived class must determine when to enable and disable subpages.


AcSection::EnableSubPage method

Enables using subpages for the section.

Syntax

Sub EnableSubpage( )

Description

Enables using subpages for the section. The predefined section classes call this method automatically. The subpage will actually appear in the page only if the Subpage property is set for this section.

Sections derived directly from AcSection start with their subpages disabled. The derived class must determine when to enable subpages.


AcSection::FinishConnection method

See also

Closes the connection.

Syntax

Sub FinishConnection( connection As AcConnection )

connection

The connection to close.

Description

By default, this method closes the connection. The method is called only when this section has a connection. You should override this method to do nothing if you overrode the ObtainConnection( ) method to return a shared connection. (If the connection is shared, then you probably want to leave it connected so that a later section can continue to use it.)


See also

AcSection::ObtainConnection method


AcSection::FinishFlow method

See also

Called at the end of each flow.

Syntax

Sub FinishFlow

Description

The page list calls FinishFlow( ) for each active section at the end of each flow. There will be one call to EndFlow( ) for each call to CommittedToFlow( ). This is the place to add page footers.


See also

AcSection::FinishPage method

AcSection::StartFlow method

AcSection::StartPage method


AcSection::FinishPage method

See also

Tells a section that a new page is finishing.

Syntax

Sub FinishPage( page As AcBasePage )

page

A reference to the page that is ending.

Description

FinishPage( ) identifies that a page is finishing and gives you an opportunity to insert custom code. If you override FinishPage, call the Super version first.

In derived classes, the page list calls each object's FinishPage( ) to check if the objects want to add information to a page before the page is finished.


See also

AcSection::FinishFlow method

AcSection::StartFlow method

AcSection::StartPage method


AcSection::GetContents method

See also

Returns the list of contents for this section.

Syntax

Function GetContents( ) As AcList

Description

This method is simply an override of the method defined in AcReportComponent that returns the ContentList variable. See the description in AcReportComponent for more information.

Return value

The list of contents for this section.


See also

AcReportComponent::GetContents method


AcSection::GetCurrentRow method

Returns the current data row.

Syntax

Function GetCurrentRow( ) As AcDataRow

Description

The GetCurrentRow method returns the data row that the section is currently processing.

Return value

A reference to the current data row.


AcSection::NewConnection method

Instantiates the connection for this section.

Syntax

Function NewConnection( ) As AcConnection

Description

Instantiates the connection for this section. Override this method if you want to customize the selection of the connection component. By default, this method instantiates the connection, if any, that you specified in the Connection slot in the structure pane.

Return value

The new connection.


AcSection::NewPage method

Lets the section determine the page on which it appears.

Syntax

Function NewPage( ) As AcPage

Description

NewPage( ) lets the section determine the page on which it appears. The page you instantiate here takes precedence over the default page that the page list supplies.

Return value

The page on which the section appears.


AcSection::NewSubPage method

Instantiates a new subpage for the section.

Syntax

Function NewSubPage( ) As AcSubPage

Description

The NewSubpage( ) method instantiates a new subpage for the section. By default, it instantiates the subpage (if any) that you placed in the Subpage slot for the section in the Design Editor.

Return value

The new subpage instantiated.


AcSection::ObtainConnection method

Creates a connection for this section.

Syntax

Function ObtainConnection( ) As AcConnection

Description

By default, this method instantiates and opens the connection, if any, that you placed into the Connection slot of this section in the structure pane. You can override this method to return a shared connection defined elsewhere.

Return value

The connection obtained for this section.


AcSection::PageBreakAfter method

See also

Returns the value of the PageBreakAfter property.

Syntax

Function PageBreakAfter( ) As Boolean

Description

The PageBreakAfter( ) method returns the value of the PageBreakAfter property by default. You can override this method to take control of the return value.

Return value

The value of the PageBreakAfter property.


See also

AcSection::PageBreakBefore method


AcSection::PageBreakBefore method

See also

Returns the value of the PageBreakBefore property.

Syntax

Function PageBreakBefore( ) As Boolean

Description

The PageBreakBefore( ) method returns the value of the PageBreakBefore property. You can override this method to take control of the return value.

Return value

The value of the PageBreakBefore property.


See also

AcSection::PageBreakAfter method


AcSection::StartFlow method

See also

Called at the beginning of each flow.

Syntax

Sub StartFlow( flow As AcFlow ) As Boolean

flow

The flow that is starting.

Description

The page list calls the StartFlow( ) method for each registered section at the top of each new flow. There will be one or more calls to StartFlow( ) for each call to StartPage( ). This is the place to add page headers and reserve space for page footers.

StartFlow( ) returns True if the section was successfully started on the flow, False if there was not enough room in the flow to contain the header, footer, or subpage for the section. In this case, the page list ends the current flow, starts a new flow, and calls this method again for the new flow.


See also

AcSection::FinishFlow method

AcSection::FinishPage method

AcSection::StartPage method


AcSection::StartPage method

See also

Called at the start of each new page.

Syntax

Sub StartPage( page As AcBasePage )

page

A reference to the page that is starting.

Description

StartPage( ) tells a section that a new page is starting.


See also

AcSection::FinishFlow method

AcSection::FinishPage method

AcSection::StartFlow method


AcSection::StopAfterCurrentFrame method

See also

Stop processing after the current frame is added to a page.

Syntax

Sub StopAfterCurrentFrame( )

Description

StopAfterCurrentFrame( ) finishes the current frame by placing it on a page, but then produces no more output. The section will not display any totals. Note that finishing the frame might entail creating a new page to contain the frame.


See also

AcSection::StopAfterCurrentRow method

AcSection::StopNow method


AcSection::StopAfterCurrentRow method

See also

Stop processing after the current row is complete.

Syntax

Sub StopAfterCurrentRow( )

Description

StopAfterCurrentRow( ) processes the current data row before stopping. The section outputs the frame(s), if any, for the row and outputs totals, and so on, depending on the kind of frame. You use this method when you want to stop processing a section after a given row, or a given number of rows. The resulting report will look as if the input data stream contained only rows up to the current row; all subsequent rows are silently ignored.


See also

AcSection::StopAfterCurrentFrame method

AcSection::StopNow method


AcSection::StopNow method

See also

Stops processing a data row.

Syntax

Sub StopNow( )

Description

StopNow( ) stops the section; it discards any partially completed frames or partially processed data rows. Use this when you want to stop output at the end of a page. Do not create aggregates if you use this method because the aggregates will be incorrect.


See also

AcSection::StopAfterCurrentFrame method

AcSection::StopAfterCurrentRow method


Class AcSequentialSection

Methods

A class that generates multiple, sequential components.

Description

The AcSequentialSection class lets you generate multiple, sequential components. For example, use it to produce multiple reports within a single report object, as is done in the Sales Forecast example, where the report lists the top deals followed by positive changes, then followed by negative changes. Or, you can produce multiple components for a single data row, such as a frame that displays customer information followed by a nested report that lists the customer's current orders.

Think of the sequential section as a converter: it converts a slot that takes just one component (such as the Content slot of the top-level AcReport) into a slot that takes multiple components. The contents of a sequential section can be any kind of report component including frames or other sections. The sequential section generates its contents in the order that they appear in the structure pane of the Design Editor.

You can write custom code that selects which contents to generate and which to skip by overriding the SelectContent( ) method.

The component that contains the sequential section calls Build( ) or BuildFromRow( ) for the sequential section. The container calls the Build( ) method if the container has no data row available, and calls BuildFromRow( ) if a data row is available. Within the sequential section, these two methods perform identical processing, except that Build( ) will in turn call the Build( ) method on its contents, and BuildFromRow( ) will call BuildFromRow( ) on its contents.

Properties

Property	Type	Description
Content	AcReportComponent	Lists the sequential components you want to produce.
Methods

Method	Type	Description
Build( )	N/A	Builds each component within the sequential section.
BuildFromRow( )	AcBuildStatus	Runs each report for the sequential section based on a data row.
NewContent( )	AcReport Component	Instantiates one of the list of contents for this section.
SelectContent( )	Boolean	Allows the section to filter out some of its contents.


Methods for class AcSequentialSection

AcSequentialSection::Build method

AcSequentialSection::BuildFromRow method

AcSequentialSection::NewContent method

AcSequentialSection::SelectContent method


AcSequentialSection::Build method

See also

Builds each component within the sequential section.

Syntax

Sub Build( )

Description

Build( ) generates the contents of the sequential section in the order in which they appear in the structure pane. Since Build( ) takes no data row, when this method builds its contents, it calls the Build( ) method on each of the contents. The following is the process that Build( ) uses to build the contents for the sequential section:

1	Calls SelectContent( ) to determine whether to generate the first component.

2	Calls NewContent( ) to instantiate the component.

3	Calls the component's Start( ) method.

4	Calls the component's Build( ) method.

5	Calls the component's Finish( ) method.

6	Adds the component to the output page (if needed).

7	Loops back to step 1 to process the next component.

The processing for BuildFromRow( ) is identical except for step 4, which first calls the content's BuildFromRow( ) method with the row passed to BuildFromRow( ), then calls the content's BuildFromRow( ) method a second time with a null data row to inform the content that no additional rows are available.

You generally do not override this method; instead, override SelectContent( ) or NewContent( ) on your subclass of AcSequentialSection, or override the Start( ), Build( ), or Finish( ) methods of the contained components.


See also

AcSequentialSection::BuildFromRow method


AcSequentialSection::BuildFromRow method

See also

Builds each component within the sequential section based on a data row.

Syntax

Function BuildFromRow( row As AcDataRow) As AcBuildStatus

row

The row to use in setting the value of the control.

Description

The BuildFromRow( ) method works almost identically to Build( ); see Build( ) for details.

Return value

Each sequential section can process only one data row. As a result, BuildFromRow( ) accepts the first row that it is given (returning True), but will reject the second row (returning False).


See also

AcSequentialSection::Build method


AcSequentialSection::NewContent method

Instantiates one of the list of contents for this section.

Syntax

Function NewContent( index As Integer) As AcReportComponent

index

The number of the content component.

Description

The sequential section identifies its contents in order from 1 to the number of contents. The index passed to this function corresponds to the position of the content component within the content list that you see in the structure pane of the Design Editor. By default, this method simply looks in the internal database for the name of the component that exists in the position given by index and instantiates that component.

If you want to do custom processing, you can override this method to decide which component to instantiate for a given index position. If you override this method, you must be aware of several points: First, if you override this method to take control of which component to instantiate for each index location, then any contents you specify in the structure pane are ignored. To change the set of components that the sequential section generates, you must change your override of this method. Second, the sequential section assumes that when NewContent( ) returns Nothing, the index is one greater than the number of contents in this section. Thus, you cannot instantiate components for indexes 1 and 2, none for 3, but again instantiate a component for index 4. The sequential section never calls this method with index 4 if index 3 returns Nothing.

You don't need to completely replace the default behavior. You could, for example, take control of what component to instantiate for index 1, but call the super class method to handle all other components.

Return value

The component that is instantiated.


AcSequentialSection::SelectContent method

Example

Allows the section to filter out some of its contents.

Syntax

Function SelectContent( index As Integer, row As AcDataRow) As Boolean

index

The index of the sequential section.

row

If the sequential section is being built through the BuildFromRow( ) method, then the row parameter gives you access to the data row provided by the container. If the section is being built through the Build( ) method, the row variable will be Nothing.

Description

The SelectContent( ) method lets you conditionally select which contents of the sequential section to generate. The index passed to this method has the same meaning and value as the index passed to NewContent( ). The sequential section will call the SelectContent( ) method to determine if it should then call newContent( ) to instantiate the component. This method returns True if the component is to be selected, False if not. If False, then the sequential section simply increments the index and calls this method again with the next index. As a result, if you override this method, you must ensure that it eventually returns True for at least one index value for which NewContent( ) will return Nothing, or the sequential section will be locked in an infinite loop.

You can find out what component corresponds to a given index position by calling GetContentName( ).


Example

The following example prints a customer contact report only if the customer's account is past due.

Function SelectContent( index As Integer, row As AcDataRow ) As Boolean

Dim cust	As CustomerRow

'Get the customer row

Set cust = row

'Check if this is the index for the contact report.

If GetContentName( "Content", index ) = "ContactReport" Then

SelectContent = ( cust.PastDue > 0 )

Else

SelectContent = True

End If

End Function

Using SelectContent( ) to decide whether to produce a specific content is just a convenience. You can produce the same result by inserting a conditional selection between the sequential section and the component that is to be conditionally selected.

Return value

True if the section wants to include the given content in the report.

False if the section does not want to include the given content in the report.


Class AcSimplePageList

Builds a page list with a series of pages, all of the same style.

Description

Provides a report style in which all pages have the same layout.

Properties

Property	Type	Description
PageStyle	AcPage	Specifies the single page style to use when creating the report.


Class AcSingleInputFilter

See also   Methods

A data filter--one type of data adapter--that accepts input from one data adapter, processes the data, then passes it to the next data adapter or the report.

Description

AcSingleInputFilter is a data filter that accepts one data adapter as its input and filters each data row. Create a derived class to define the filtering.

You can create filters to:

•	Select certain rows and reject others. This is a selection filter.

•	Convert a row from one format to another. This is a projection filter.

•	Split large input rows into smaller rows needed by your report. For example, if your input row gives twelve months of financial data per data row, but your report needs the data organized as one month per row, you can create a filter to split up the row.

•	Combine data rows into a larger aggregate row. For example, you could do the opposite of the above filter to combine data rows that contain one month of financial data per row into a large row that contains twelve months of data per row.

•	Add to fields in a data row by doing a lookup on an in-memory or disk-based table. This is a lookup filter. For example, you could do an in-memory lookup of a transaction code on each row to find its description, then copy the description into the data row.

•	Sort rows. This is a sort filter. Actuate provides a memory-based sort filter called AcMemoryDataSorter.

The uses of a single input filter are many. If your application needs to combine several of the above transformations into a single data stream, your application will be easier to build, maintain, and understand if you create a separate filter for each transformation, then chain these transformations together to form the data stream.

If your data source is an SQL query, then you can increase the performance of your report by doing as much filtering as possible in the SQL query itself. Note that data filters are optional, and that a data stream can have multiple data filters.

The input adapter

A data filter reads data from another data adapter called the input adapter. You can specify the input adapter in one of two ways:

•	You can simply drop the input adapter into the Input slot of the data filter in the structure pane.

•	You can call SetInput( ) from code to programmatically set the input adapter.

If you drop the input adapter into the Input slot, then the single input filter takes responsibility for instantiating the input adapter by providing the input adapter with a connection, starting the input adapter when the filter itself starts, and finishing the input adapter when the filter itself finishes.

If you set the input adapter with a call to SetInput( ), then you can pass either an open or unopened data adapter. If you pass an opened data adapter, then the single input filter assumes that your application will close this adapter, and so the single input filter will not close the input adapter for you. If you pass an unopened input adapter, then the single input filter takes responsibility for starting the input adapter when the filter itself starts and for finishing the input adapter when the filter itself finishes. If you call SetInput( ), do so before calling the Start( ) method for the filter.

In either case, use the variable InputAdapter to access the input adapter.

If you specify an input adapter in the structure pane, but then subsequently call SetInput( ) in your code, the input adapter passed to SetInput( ) takes precedence.

Creating a filter

To define a filter, override the Fetch( ) method. See the description of Fetch( ) for details.

Variables

Variable	Type	Description
InputAdapter	AcDataAdapter	References the data adapter (input adapter) that supplies input to this data filter.
Methods

Method	Type	Description
Fetch( )	AcDataRow	Fetches a row from the filter.
NewInputAdapter( )	AcDataAdapter	Instantiates the input adapter.
SetInput( )	N/A	Specifies the input adapter for this data filter.


See also

Class AcDataAdapter

Class AcDataSource

Class AcMemoryBuffer

Class AcMultipleInputFilter


Methods for class AcSingleInputFilter

AcSingleInputFilter::Fetch method

AcSingleInputFilter::NewInputAdapter method

AcSingleInputFilter::SetInput method


AcSingleInputFilter::Fetch method

Example   See also

Fetches a row from the filter.

Syntax

Function Fetch( ) As AcDataRow

Description

To define a filter, you need only to override this method. By default, Fetch( ) in the single input filter simply reads and returns a row from the input adapter. The following shows how to create a Fetch( ) method that filters out all customers except those in California.


Example

Function Fetch( ) As AcDataRow

'Loop to read rows until there are no more rows, or until

'finding a customer in California.

Do While True

'Fetch the next row from the input

Set Fetch = InputAdapter.Fetch( )

If Not Fetch Is Nothing Then

Exit Function

End If

'Return the row if the customer is in California.

If Fetch.GetValue( "State" ) = "CA" Then

Exit Function

End If

Loop

End Function

Return value

A reference to the retrieved row if Fetch( ) retrieves a row.

Nothing if there are no more rows to retrieve.


See also

AcDataAdapter::Fetch method


AcSingleInputFilter::NewInputAdapter method

Instantiates the input adapter.

Syntax

Function NewInputAdapter( ) As AcDataAdapter

Description

NewInputAdapter( ) instantiates the data adapter class, if any, that you dropped into the Input slot of single input filter in the structure pane. You can override this method if you want to programmatically decide which adapter to instantiate.

Return value

The new data adapter, if any.


AcSingleInputFilter::SetInput method

Sets the input adapter for this data filter.

Syntax

Sub SetInput( adapter As AcDataAdapter )

adapter

The data adapter that supplies data rows to this filter.

Description

Call SetInput( ) to specify the input adapter to use with this filter. The adapter specified here takes precedence over the existing one in the Input slot in the structure pane.


Class AcSingleList

Implements a singly linked list.

Description

AcSingleList is derived from AcList. It implements a singly linked list. You should declare your variables as AcList and then set them to AcSingleList to carry out the actual implementation of the singly linked list methods.

See AcList for an example of using a singly linked list.


Class AcSingleListIterator

A concrete class to iterate over a list.

Description

AcSingleListIterator is a concrete class, derived from AcListIterator. It provides methods to iterate over a singly linked list.

See AcList for an example of how to iterate over a singly linked list.


Class AcSqlQuerySource

See also   Methods

A class that retrieves data from an SQL SELECT statement.

Description

AcSQLQuerySource is the base class for query data sources that you build in the Actuate Query Builder. AcSQLQuerySource provides the framework for executing an SQL SELECT statement including

•	Processing ad-hoc parameters.

•	Handling dynamic ordering established by group sections.

•	Assembling the SELECT statement from its component parts.

•	Preparing the SQL statement and opening a cursor.

•	Binding static parameters.

•	Binding the data row to the database cursor.

The following figure illustrates the operation of an AcSQLQuerySource:

The normal way to create a query data source is to use the Actuate Query Builder. You can, however, programmatically create the query data source. If you do, you must either set the various variables that hold the fragments of the SELECT statement or override ObtainSelectStatement( ) to return the complete statement. You must also override BindStaticParameters( ) (defined in AcDatabaseSource) to bind static parameters and BindDataRow( ) (also defined in AcDatabaseSource) to bind the data row to the cursor.

Variables

Variable	Type	Description
FromClause	String	The FROM clause.
GroupByClause	String	The GROUP BY clause.
HavingClause	String	The HAVING clause.
OrderByClause	String	The ORDER BY clause.
SelectClause	String	The SELECT clause.
WhereClause	String	The WHERE clause.
Properties

Property	Type	Description
Query	Query	An internal representation of the query that this query source class uses. The user uses the Query Builder to assemble the query.
Methods

Method	Type	Description
AddSortKey( )	N/A	Changes the sort order at run time, using the column name value specified in the Key property of the group section.
GetStatementText( )	String	Returns the SELECT statement sent to the database.
ObtainSelect Statement( )	String	Returns a SQL statement.
SetAdHocParameter( )	N/A	Processes an ad-hoc parameter.
SetupAdHoc Parameters( )	N/A	Generated. The framework overrides this method to call SetAdHocParameter( ) repeatedly until all ad hoc parameters are processed.


See also

Class AcDataAdapter

Class AcDatabaseSource

Class AcDataRow

Class AcDataSource

Class AcDBConnection


Methods for class AcSqlQuerySource

AcSqlQuerySource::AddSortKey method

AcSqlQuerySource::GetStatementText method

AcSqlQuerySource::ObtainSelectStatement method

AcSqlQuerySource::SetAdHocParameter method

AcSqlQuerySource::SetupAdHocParameters method


AcSqlQuerySource::AddSortKey method

Specifies a sort key column at run time.

Syntax

Sub AddSortKey( keyName As String, sortSense As String )

keyName

The name of one of the columns in the SELECT clause.

sortSense

The direction of the sort. This must be one of the two constants: SortAscending or SortDescending.

Description

Group sections provide the ability to automatically update the ORDER BY clause of the SELECT statement for a SQL query source to match the sequence needed by your report. The group sections inform the SQL query source of the preferred sort order by calling AddSortKey( ) and passing the Key property value of the group section.

If you are writing custom code that uses a query data source, your custom code can call AddSortKey( ) to customize the sort order of the data. The value you pass must match the column name or column alias that appears in the SELECT clause of your SELECT statement. This method is available only if you allow the SQL query source to assemble your statement from the fragments.

AcSqlQuerySource returns True from a call to CanSortDynamically( ) to indicate that custom sorting is supported. If your custom subclass cannot support custom sorting, then you should override CanSortDynamically( ) to return False.


AcSqlQuerySource::GetStatementText method

Returns the text of the SELECT statement for the SQL query source.

Syntax

Function GetStatementText( ) As String

Description

Call GetStatementText( ) if you want to check the SELECT statement being sent to the database. You can call this method only after calling Start( ).

Return value

The current SELECT statement as a string.


AcSqlQuerySource::ObtainSelectStatement method

Returns a SQL SELECT statement.

Syntax

Function ObtainSelectStatement( ) As String

Description

ObtainSelectStatement( ) assembles a SQL SELECT statement from the component parts entered in the Actuate Query Builder. Override this method to create custom SQL SELECT statements.

Return value

A SQL SELECT statement as a string.


AcSqlQuerySource::SetAdHocParameter method

See also

Sets the value of a single ad hoc parameter.

Syntax

Sub SetAdHocParameter( columnName As String, dataType As String, value As String)

columnName

The name of a database column. The column need not appear in the SELECT clause, but must be a column available in one of the tables in the FROM clause.

dataType

The type of the data column. The data type must be one of String, Integer, Long, Currency, Single, Double, or Date.

value

The value of the ad-hoc parameter.

Description

Your query can contain any number of ad hoc parameters, which provide additional conditions for the WHERE clause of a SELECT statement. SetAdHocParameter( ) sets the value of a single ad-hoc parameter. An ad-hoc parameter is identified by a column name. The column name need not appear in the SELECT clause of your SELECT statement, but must be a column available in one of the tables in the FROM clause. The value of the parameter is either an empty string (which means the parameter is ignored), or an ad-hoc expression using the syntax described in the query data streams chapter of the Building Reports book.


See also

AcSqlQuerySource::SetupAdHocParameters method


AcSqlQuerySource::SetupAdHocParameters method

Example   See also

Adds ad-hoc parameters to the query.

Syntax

Sub SetupAdHocParameters( )

Description

The AcSqlQuerySource class calls SetupAdHocParameters( ) to enable your derived class to set the value of its ad-hoc parameters. Actuate normally generates this method for you. If you programmatically create your class and your class provides ad-hoc parameters in the Requester, you must override this method. Your override calls SetAdHocParameters( ) to set the value of each parameter.


Example

Sub SetupAdHocParameters( )

SetAdHocParameter( "Customer.State", "String", "NameParm" )

SetAdHocParameter( "Customer.Balance", "Currency", "BalanceParm" )

End Sub


See also

AcSqlQuerySource::SetAdHocParameter method


Class AcStoredProcedureSource

See also   Methods

A class that retrieves data from a stored procedure.

Description

AcStoredProcedureSource is the base class for creating stored procedure data sources. Use this class to take advantage of automated design facilities in the Developer Workbench to create data sources that use a stored procedure as a source of data: no coding is necessary. AcStoredProcedureSource provides the framework for executing a stored procedure including

•	Creating and managing parameters

•	Creating and managing row variables

•	Executing the stored procedure

Use AcStoredProcedureSource only with databases that support stored procedures.

AcStoredProcedureSource supports procedures that return one result set. If a stored procedure returns multiple result sets, Actuate uses only the first one. To retrieve data from a stored procedure that has a complex result set, you must create your own data source class. See Programming with Actuate for more information on using Actuate Basic to call stored procedures.

Parameters

AcStoredProcedureSource handles input, output and input/output stored procedure parameters. Stored procedure input parameters are similar to static parameters in the WHERE clause of a query.

If a stored procedure parameter has output parameters (output or input/output), AcStoredProcedureSource creates separate variables for the these parameters. These parameter output variables are cleared when the data source is initialized and started to allow repeated execution of the stored procedure. AcStoredProcedureSource sets the variables as soon as the data is available from the stored procedure. From the standpoint of Actuate Basic, the data is available after the last row of data has been retrieved from the stored procedure.

Row variable creation

Actuate creates and names variables in the AcDataRow class for a stored procedure in a manner that is similar to the way that the variables are created when you use the AcSqlQuerySource class. When a column in the result set has no name, Actuate creates a variable for it in the AcDataRow class and gives that variable the name columnX, where X is column number of the unnamed column in the result set. For example, if the result set returned by the stored procedure has three columns and the second is unnamed, Actuate creates an AcDataRow variable named Column2 for the second column.

Variables

Variable	Type	Description
OwnerName	String	A database user name.
ProcedureName	String	Name of the stored procedure.
QualificationOption	String	Specifies how the stored procedure call is to be qualified at runtime.
QualifierName	String	A database qualifier for the stored procedure.
Do not modify these variables.

Properties

Property	Type	Description
StoredProcedureDef	N/A	An internal representation of the stored procedure. It can only be edited using the Stored Procedure Builder.
After you select a stored procedure using the Stored Procedure Browser, AcStoredProcedureSource retrieves the definition of the stored procedure from the database and stores the definition in StoredProcedureDef. This is a complex property that you can edit only with the Stored Procedure Builder. AcStoredProcedureSource retrieves the following information from the database when a connection and stored procedure are specified.

•	Procedure name. The name of the procedure

•	Owner name. A database user name that the stored procedure is scoped within.

•	Qualifier name. A database qualifier the procedure is scoped within. For Sybase stored procedures, the qualifier represents the name of a Sybase database. For Microsoft SQL server stored procedures, the qualifier represents the name of a Microsoft database.

•	Qualification option. Specifies how the stored procedure call is to be qualified at run time. There are three options: procedure name only, owner.procedurename or qualifiername.ownername.procedurename.

•	Return type information. The return type of the stored procedures return value. Some stored procedures do not use a return value.

•	Column information. Contains the following column information:

•	Column name. The name of an output column. This name is used to create a name for a variable in the row class.

•	Column type information. Information about the data type of the column.

•	Parameter information. The following parameter information:

•	Parameter name. The name of a parameter in the stored procedure. This name is used to create a name for a parameter variable on the stored procedure class.

•	Parameter type information. Information about the data type of the parameter.

•	Column kind. Parameters can be used for input, output or both.

 AcStoredProcedureSource uses column and parameter information to specify report data rows.

Methods

Method	Type	Description
AddSortKey()	N/A	Changes the sort order at run time, using the column name value specified in the Key property of the group section.
ProcedureReturnValue()	variant	Returns the return value of the procedure.


See also

Class AcDataAdapter

Class AcDatabaseSource

Class AcDataRow

Class AcDataSource

Class AcDBConnection

Class AcSqlQuerySource


Methods for class AcStoredProcedureSource

AcStoredProcedureSource::AddSortKey method

AcStoredProcedureSource::ProcedureReturnValue method


AcStoredProcedureSource::AddSortKey method

Specifies a sort key column at run time.

Syntax

Sub AddSortKey( keyName As String, sortSense As String )

keyName

The name of the variable (or the column the variable is associated with) by which to sort the data.

sortSense

The direction of the sort. This must be one of the two constants: SortAscending or SortDescending.

Description

Group sections provide the ability to automatically update the ORDER BY clause of the SELECT statement for a SQL query source to match the sequence needed by your report. The group sections inform the SQL query source of the preferred sort order by calling AddSortKey( ) and passing the Key property value of the group section.

Each data adapter (data source, in the case of stored procedures) indicates whether it can sort data dynamically according to how the group sections want the data sorted. If the CanSortDynamically( ) method returns True, the data adapter sorts the data according to the AddSortKey( ) calls. Each call to AddSortKey( ) indicates a variable in the data row to sort the data by, and the sort sense for that variable. The calls to AddSortKey( ) are made in order of precedence for the sort. The first call indicates the first sort key, the second indicates the second sort key, and so on.   The first parameter to AddSortKey( ) indicates the variable to be used by a name. That name is either the actual name of the variable, or if the data source is a query or stored procedure data source, the name indicates the name of a column the variable is associated with.

If you are writing custom code that uses a query data source, your custom code can call AddSortKey( ) to customize the sort order of the data. The value you pass must match the column name or column alias that appears in the SELECT clause of your SELECT statement. This method is available only if you allow the SQL query source to assemble your statement from the fragments.

AcSqlQuerySource returns True from a call to CanSortDynamically( ) to indicate that custom sorting is supported. If your custom subclass cannot support custom sorting, then you should override CanSortDynamically( ) to return False.

If a data source cannot sort data dynamically for a report section and its associated group sections, the report section automatically instantiates a sort filter. If you use a data source which cannot sort dynamically, but you know that the data is already in the correct sort order, set the AcReportSection IsSorted property to TRUE. Setting IsSorted to TRUE tells AcStoredProcedureSource that the data is already sorted.


AcStoredProcedureSource::ProcedureReturnValue method

Returns the return value of the procedure.

Syntax

Function ProcedureReturnValue(  )

Description

This is method returns the return value of a stored procedure. Note that it will be up to the developer to do something useful with this return value if needed.

Return value

Return value of the procedure is of type variant to accommodate procedures of different return types.


Class AcSubPage

A subpage fits inside a flow.

Description

AcSubpage lets you introduce a different collection of flows within a page. You use a subpage to dynamically switch from one column to two columns on the same page. For example, you might produce a report that lists orders and the items on the order. You may want the order information to fill the full width of the page. However, the item information may be short enough that you would like to list it in two columns. You do this by adding a subpage to your design and creating two flows within the subpage. Actuate places the subpage inside the flow in your (real) page, and all subsequent output goes into the subpage. You can ensure that the contents of each flow are the same (even, or balanced) by setting the subpage's BalanceFlows property to True.

Resizing the subpage

Subpages provide the ability to grow or shrink depending on the number of frames that appear within them. Unless you set the CanShrink property to True, subpages will get no smaller than the size that you draw them. However, they can grow as large as the flow in which they appear. If you allow a subpage to shrink, you can set the MinimumSize property to determine how small the subpage can get.

A subpage provides a simple model for moving and resizing its contents based on where contents appear in the subpage relative to the flows in that subpage. Consider the following diagram:

Flow 1 and Flow 2 are flows. The items drawn with letters indicate various controls. Controls fall into one of three groups depending on how changes in size to the subpage affects the controls.

The first group are those that remain constant. A control remains constant if its top is above the midpoint, and its bottom is above the flow bottom. In the diagram, controls X, C, D, and F will remain unchanged as the subpage resizes.

The second group are controls that will maintain the same size, but whose top position will change to maintain a constant distance from the bottom of the subpage. Controls fall into this group if their top is below the midpoint. In the diagram, controls E, G, and Y fall into this group.

The third group are those controls that will maintain a constant position, but will change size by the same amount that the flow changes size. A control falls into this group if its top is at or above the flow top, and its bottom is at or below the flow bottom. Controls A and B in the diagram fall into this group. This allows you to create rulings along side the flows.

There are times when you may want to have a ruling grow or shrink along with the flow, but you want the ruling to be somewhat shorter than the flows themselves. You can set the ResizeRegion property to indicate the tolerance for resizing. If you set this property, the subpage will add its value to flow top and subtract it from flow bottom to shrink the region that a control must span to be resized.

Properties

Property	Type	Description
CanShrink	Boolean	Whether to allow the subpage to shrink smaller than the size that you draw it in the Design Editor.
Margins	AcMargins	The amount of extra space, if any, to provide between the subpage and its enclosing flow.
MinimumHeight	Integer	If you allow the control to shrink, then this property specifies the minimum flow height.
ResizeRegion	Integer	The amount (in twips) by which to decrease the size of the region that a control must span for it to be resized when the subpage is resized.
Rounding	AcRounding	The amount of rounding, if any, to apply to the corners of the subpage.
Shadow	AcShadow	The properties of the shadow, if any, to display for the subpage.


Class AcSummaryGraph

Methods

Provides the mechanism for building graph data from data rows.

Description

The AcSummaryGraph is a subclass of AcGraph that summarizes rows into an array of series and categories. Series correspond to data sets in the graph. Categories correspond to data points. Each series and category is identified with a key computed from a data row. Together, these form an index into a grid given by (category_key, series_key). This class

•	Saves the set of data rows.

•	Makes a second pass to determine the set of series and categories.

•	Makes a third pass to compute the aggregates in each cell.

•	Makes a final pass over the summarized data to populate the graph legend, series, and points arrays.

Methods

Method	Type	Description
BuildFromRow	AcBuildStatus	Gathers the data rows.
Finish	N/A	Creates the graph data from an accumulated set of rows.


Methods for class AcSummaryGraph

AcSummaryGraph::BuildFromRow method

AcSummaryGraph::Finish method


AcSummaryGraph::BuildFromRow method

Gathers the data rows.

Syntax

Function BuildFromRow( row As AcDataRow ) As AcBuildStatus

row

The data row to use.

Description

Gathers the data rows.

Return value

The status of the build.


AcSummaryGraph::Finish method

See also

Creates the graph data.

Syntax

Sub Finish( )

Description

Creates the graph data from an accumulated set of rows. See AcBaseFrame::Finish method for an example showing how to use the Finish( ) method.


See also

AcBaseFrame::Finish method


Class AcSybaseConnection

Establishes a connection to a Sybase database.

Description

Use the AcSybaseConnection class to establish a connection to a Sybase database. The application must set the server name, user name, and password prior to connecting. Once connected, the application should not change these values.

Variables

Variable	Type	Description
Password	String	The client password for the connection.
ServerName	String	The client server name for the connection.
UserName	String	The client user name for the connection.
Properties

Property	Type	Description
Password	String Variable	The client password for the connection.
ServerName	String Variable	The client server name for the connection.
UserName	String Variable	The client user name for the connection.
CsDllPath	String Variable	The name of Sybase's server DLL, required to connect to Sybase System 10 and System 11 servers.
CtDllPath	String Variable	The name of Sybase's client DLL, required to connect to Sybase System 10 and System 11 servers.


Class AcSybaseDBLibConnection

Establishes a connection to a Sybase database version 4.9.x.

Description

Use the AcSybaseDBLibConnection class to establish a connection to a Sybase database version 4.9.x. The application must set the DLL path, server name, user name, and password prior to connecting. Once connected, the application should not change these values.

Variables

Variable	Type	Description
DllPath	String	The name of the DLL providing client database.
Password	String	The client password for the connection.
ServerName	String	The client server name for the connection.
UserName	String	The client user name for the connection.
Properties

Property	Type	Description
DllPath	String Variable	The name of the DLL providing client database. Default is the most common name used for the connectivity DLL provided by Sybase.
Password	String Variable	The client password for the connection.
ServerName	String Variable	The client server name for the connection.
UserName	String Variable	The client user name for the connection.


Class AcTextControl

A class you use in the report design to display string data.

Description

AcTextControl is a data control you typically use to store and display string data from a data row. You can, however, also use it to display values returned by methods or functions, such as PageNo$( ) or Date$( ), as long as the return value is a string.

The text control is typically used for displaying one line from a table column, such as a name or address, but it can be used for multiline text as well. To display multiline text, set the MultiLine property to True. You should also specify a size that will accommodate all the lines of text. If you do not know the length of the text, use the Clip property to select how Actuate handles extra characters.

AcTextControl defines a DataValue variable to store the string value. The framework generates SetValue( ) to set the value in DataValue. SetValue( ), turn, uses the value expression you assign to the ValueExp property to generate the value. Override SetValue( ) if you want to take control of setting the control's data value.

If you want to change the value or properties of the text control when the Factory is building it, you can override the text control's BuildFromRow( ) method. For example, you can change the properties of the control depending on the value stored in the DataValue variable. For an example of how to accomplish this task, see AcDataControl::BuildFromRow method.

Variables

Variable	Type	Description
DataValue	String	Holds the string value.


Class AcTitleBodyPageList

Methods

Builds a page list with a title page, followed by a simple page list.

Description

The AcTitleBodyPageList class builds a page list with a title page, followed by all other pages of another style.

You can insert title pages into your report. For example, you could design a report that printed the customer name in a large font on a single page, then produce body pages as necessary for that customer, and repeat that scenario for all customers.

Properties

Property	Type	Description
BodyPage	AcPage	The page style to use for all other pages.
TitlePage	AcPage	The page style to use for the first page.
Methods

Method	Type	Description
NewBodyPage( )	AcPage	Instantiates the body page.
NewTitlePage( )	AcPage	Instantiates the title page.


Methods for class AcTitleBodyPageList

AcTitleBodyPageList::NewBodyPage method

AcTitleBodyPageList::NewTitlePage method


AcTitleBodyPageList::NewBodyPage method

Instantiates the body page.

Syntax

Function NewBodyPage( ) As AcPage

Description

Instantiates a new body page.


AcTitleBodyPageList::NewTitlePage method

Instantiates the title page.

Syntax

Function NewTitlePage( ) As AcPage

Description

Instantiates the new title page.


Class AcTopDownFlow

Methods

Adds frames to a flow from the top to the bottom.

Description

The top-down flow fills with frames in the standard top-down order. The first frame starts at the top of the flow. Then, each subsequent frame is placed just below the previous frame. When the framework receives a frame that does not fit in the remaining space in the flow, the framework advances to the next flow or page.

If both your flow and frames have a border, your layout might look better if you provide some extra margins between the flow and the frames. The Margins property of frames lets you create empty space between frames in the flow. The flow provides a margin that reserves empty space between the border and the contained frames.

You subclass AcTopDownFlow when you drag a flow component off of the palette.

Variables

Variable	Type	Description
Alignment	AcFlowPlacement	Specifies whether the frames are to appear left justified, centered, or right justified within the flow.
Margins	AcMargins	Space to allow between the border and the contained frames.
Properties

Property	Type	Description
Alignment	AcFlowPlacement	Specifies whether the frames are to appear left justified, centered, or right justified within the flow.
Margins	AcMargins	Space to allow between the border and the contained frames.
Methods

Method	Type	Description
AddFrame( )	Boolean	Adds the frame to the flow.
GetInsideOrigin( )	AcPoint	Returns the top of the content rectangle of the flow after allowing for margins.
GetInsideRect( )	AcRectangle	Returns the size and position of the content rectangle of the flow after allowing for margins.
GetInsideSize( )	AcSize	Returns the size of the content rectangle of the flow after allowing for margins.


Methods for class AcTopDownFlow

AcTopDownFlow::AddFrame method

AcTopDownFlow::GetInsideOrigin method

AcTopDownFlow::GetInsideRect method

AcTopDownFlow::GetInsideSize method


AcTopDownFlow::AddFrame method

See also

Adds the frame to the flow.

Syntax

Function AddFrame( frame As AcFrame ) As Boolean

frame

The frame to add to the book.

Description

The AddFrame( ) method adds the frame to the flow. If there is enough space in the flow to contain the frame, it is added to the flow and the amount of available space in the flow is adjusted accordingly. If there is not enough space, AddFrame creates a new page and adds the frame to the top of the new flow on the new page.

The frame is put in the flow based on its Alignment property set in the Content Editor.


See also

AcFlow::AddFrame method

AcPageList::AddFrame method


AcTopDownFlow::GetInsideOrigin method

See also

Returns the upper left corner of the content rectangle.

Syntax

Function GetInsideOrigin( ) As AcPoint

Description

Returns the upper left corner of the content rectangle of the flow, after allowing for margins.


See also

AcTopDownFlow::GetInsideRect method

AcTopDownFlow::GetInsideSize method


AcTopDownFlow::GetInsideRect method

See also

Returns the size and position of the content rectangle.

Syntax

Function GetInsideRect( ) As AcRectangle

Description

Returns the size and position of the content rectangle within the flow, after allowing for margins.


See also

AcTopDownFlow::GetInsideOrigin method

AcTopDownFlow::GetInsideSize method


AcTopDownFlow::GetInsideSize method

See also

Returns the size of the content rectangle.

Syntax

Function GetInsideSize( ) As AcSize

Description

Returns the size of the content rectangle, after allowing for margins.


See also

AcTopDownFlow::GetInsideOrigin method

AcTopDownFlow::GetInsideRect method


Class AcVisitor

Example    Methods

Provides a mechanism for creating a utility to visit and perform some action on report objects. AcVisitor methods provide functions that allow you to process a report object and its components in hierarchal order. You override AcVisitor methods to provide any specialized behavior for each component.

Description

The AcVisitor class allows you to create a mechanism in your report application that visits each object of your report and performs some action on it. For example, use AcVisitor to perform data extraction or save the report to a different format, such as PostScript or a simple text file. Actuate uses AcVisitor to build HTML reports from a report object.

Reports have two parallel structures:

•	The structure hierarchy, composed of the report, sections, frames and controls

•	The page hierarchy, composed of the report, page list, pages, flows, frames and controls

When you use the visitor class, you determine whether to visit the objects that comprise the structure hierarchy, or the page hierarchy.

The visitor visits each object in the chosen hierarchy by default. If the object contains other objects, the visitor visits each of those objects as well, in the order in which they appear in the report's structure pane. You can derive AcVisitor classes which skip certain components, or add behavior specific to particular components.

To use the AcVisitor class methods:

1	Open your report design in Developer Workbench.

2	Set up the visitor class:

1	Create a new Actuate Basic source file.

2	Create a new subclass of the AcVisitor class and instantiate it. The visitor class provides a visit method for each type of component. You override the method for a particular component if you want to perform operations on it.

3	Decide which report object is the visitor's starting point. For example, the AcReport component (to visit every object in a report), or a section or page.

4	Call the ApplyVisitor( ) method on the starting point. By default, the Visit method for a particular component calls the Visit method for the superclass of that component.  For example, by default VisitTextControl calls VisitDataControl.  Also by default, every method ultimately calls VisitComponent.

3	Decide which objects to visit:

•	If the application will visit the entire report, the derived visitor class must know which of the report's hierarchies to visit. Override the VisitReport( ) method to call either VisitContents( ) to visit the data hierarchy, or VisitPage( ) to visit the page hierarchy. By default, the visitor visits the data hierarchy.

•	If the application will not visit the entire report, decide which components should be included or excluded from processing. If the component has contents, the visit method for the contents is called by default. If you want to exclude the contents from being processed, override the component's visit method to inhibit the call to the component's superclass method.

4	Add special behavior for the visited objects:

Override each component's visit method to add special behavior as needed. For example, suppose that you want to generate Postscript for a report. Override the VisitPage( ) method to eject each page, and override the Visit method for each control to generate Postscript for that control.

5	Establish a mechanism to trigger visitor functions. For example, you could add a data control to your report object that starts your visit application when the user selects the control. Refer to the description for the OnLButtonClick( ) method for more information.

For example, suppose that you want to generate Postscript for a report. Override the VisitPage method to eject each page, and override the Visit methods for each control to generate Postscript for that control.

Methods

Method	Type	Description
VisitBaseFrame( )	AcBaseFrame	Visit the base frame component.
VisitBasePage( )	AcBasePage	Visit the base page component.
VisitComponent( )	AcReport Component	Visit the components of a report.
VisitConditional Section( )	AcConditional Section	Visit the conditional section component.
VisitContents( )	AcComponent	Visit the contents of a report's data hierarchy components.
VisitControl( )	AcControl	Visit the control component.
VisitCurrencyControl( )	AcCurrency Control	Visit the currency control component.
VisitDataControl( )	AcDataControl	Visit the data control component.
VisitDataFrame( )	AcDataFrame	Visit the data frame component.
VisitDataSection( )	AcDataSection	Visit the data section component.
VisitDateTimeControl( )	AcDateTime Control	Visit the date/time control component.
VisitDetailGraph( )	AcDetailGraph	Visit the detail graph component.
VisitDoubleControl( )	AcDouble Control	Visit the double control component.
VisitEllipseControl( )	AcEllipseControl	Visit the ellipse control component.
VisitFlow( )	AcFlow	Visit the flow component.
Visit Frame( )	AcFrame	Visit the frame component.
VisitFrameSetSection( )	AcFrameSet Section	Visit the frame set section component.
VisitGraph( )	AcGraph	Visit the graph component.
VisitGroupSection( )	AcGroupSection	Visit the group section component.
VisitHLCGraph( )	AcHLCGraph	Visit the AcHLCGraph component.
VisitHtmlApplet Control( )	AcHtmlApplet Control	Visit the HTML Applet control component.
VisitHtmlImage Control( )	AcHtmlImage Control	Visit the HTML image control component.
VisitHtmlObject Control( )	AcHtmlObject Control	Visit the HTML object control component.
VisitHtmlPlugIn Control( )	AcHtmlPlugIn Control	Visit the HTML Plug-in control component.
VisitHtmlReport( )	AcHtmlReport	Visit the HTML report component.
VisitHtmlRuleControl( )	AcHtmlRule Control	Visit the HTML rule component.
VisitHtmlTextFrame( )	AcHtmlText Frame	Visit the HTML text frame component.
VisitImageControl( )	AcImageControl	Visit the image control component.
VisitIntegerControl( )	AcIntegerControl	Visit the integer control component.
VisitLabelControl( )	AcLabelControl	Visit the label control component.
VisitLeftRightPageList( )	AcLeftRightPage List	Visit the left-right page list component.
VisitLeftToRightFlow( )	AcLeftToRight Flow	Visit the left-to-right flow component.
VisitLinearFlow( )	AcLinearFlow	Visit the linear flow component.
VisitLineControl( )	AcLineControl	Visit the line control component.
VisitOleContainer Control( )	AcOleContainer Control	Visit the OLE container control component.
VisitOleControl( )	AcOleControl	Visit the OLE control component.
VisitPage( )	AcPage	Visit the page component.
VisitPageList( )	AcPageList	Visit the page list component.
VisitParallelSection( )	AcParallelSection	Visit the parallel section component.
VisitRectangleControl( )	AcRectangle Control	Visit the rectangle control component.
VisitReport( )	AcReport	Visit the report component.
VisitReportSection( )	AcReportSection	Visit the report section component.
VisitSection( )	AcSection	Visit the section component.
VisitSequentialSection( )	AcSequential Section	Visit the sequential section component.
VisitSimplePageList( )	AcSimplePage List	Visit the simple page list component.
VisitSubpage( )	AcSubpage	Visit the subpage component.
VisitSummaryGraph( )	AcSummary Graph	Visit the summary graph component.
VisitTextControl( )	AcTextControl	Visit the text control component.
VisitTitleBodyPageList( )	AcTitleBodyPage List	Visit the title body page list component.
VisitTopDownFlow( )	AcTopDown Flow	Visit the top-down flow component.
VisitVisualComponent( )	AcVisual Component	Visit the visual component.


Example

The following example shows how to design a utility to perform data extraction using the AcVisitor class. The example uses visit methods to traverse the content hierarchy in the Sales Detail report object to extract the data controls for each frame to a spreadsheet that can be viewed using Microsoft Excel. The user selects a visual control in the report object to initiate the extraction process. When data extraction is complete, the example application starts Microsoft Excel which displays the spreadsheet.

The example features a report design that includes an Actuate Basic source file. The Actuate Basic source file performs the following programming actions:

1	Initializes the Basic program environment by performing the following actions:

•	Declares the class, AcDetailCsvVisitor, as a subclass of AcVisitor

•	Declares state variables needed for internal processing

•	Creates an instance of the output text file (spreadsheet)

•	Declares text file fields corresponding to the Sales Detail controls to be extracted

•	Declares subroutines that convert the values of the data controls to the form needed in the output text file

•	Declares subroutines to do special processing for different kinds of frames.

Class AcDetailCsvVisitor Subclass Of AcVisitor

' State variables:

'Channel contains system file number

'NeedComma is needed to determine when to write a comma to the file

'FileName contains output text file name

Dim Channel As Integer

Dim NeedComma As Boolean

Dim FileName As String

' Variables that make up the data row.

Dim TotalSalesForecast As Currency

Dim OfficeName As String

Dim OfficePhone As String

Dim OfficeAddress1 As String

Dim OfficeAddress2 As String

Dim OfficeTotalForecast As Currency

Dim RepTotalForecast As Currency

Dim RepExtension As String

Dim RepEmail As String

Dim RepName As String

Dim CustomerContactName As String

Dim CustomerContactPhone As String

Dim CustomerName As String

Dim CustomerAddress1 As String

Dim CustomerAddress2 As String

Dim CustomerCreditRank As String

Dim CustomerPurchPattern As String

Dim CustomerTotalForecast As String

Dim OrderNumber As Integer

Dim OrderForecastDate1 As String

Dim OrderNeededDate As String

Dim OrderNote As String

Dim OrderForecastDate2 As String

Dim OrderStatus As String

Dim ItemCategory As String

Dim ItemCode As String

Dim ItemDescription As String

Dim ItemQuantity As Integer

Dim ItemPrice As Currency

Dim ItemExtension As Currency

Dim OrderTotalQuantity As Integer

Dim OrderTotal As Currency

Dim CustomerTotalQuantity As Integer

Dim RepTotalQuantity As Integer

Dim OfficeTotalQuantity As Integer

Dim TotalQuantity As Integer

' Create instance of output text file

Sub New( )

FileName = "extract.csv"

End Sub

' Convert a number to a field in the output line.

Sub NumericField( value As Variant )

If NeedComma Then

Print #Channel, ",";

End If

Print #Channel, CStr( Value );

NeedComma = True

End Sub

' Convert a string to a field in the output line.  The string

' must be quoted. Any quotes in the string must be replaced by

' a double quote.  Newline characters are converted to spaces.

' So, a value of

'	He said "Hi!"

' Becomes:

'	"He said ""Hi!!"""

Sub TextField( value As String )

Dim i As Integer

Dim length	As Integer

Dim c As String

If NeedComma Then

Print #Channel, ",";

End If

Print #Channel, """";

length = Len( value )

For i = 1 to length

c = Mid$( value, i, 1 )

Select Case c

Case """"

Print #Channel, """""";

Case Chr$(13)

Print #Channel, " ";

Case Chr$(10)

Print #Channel, " ";

Case Else

Print #Channel, c;

End Select

Next

Print #Channel, """";

NeedComma = True

End Sub

2	Overrides VisitReportSection( ) method to perform the following actions:

•	Opens the text file for output

•	Writes labels for the text fields

•	Calls the VisitDataSection( ) method to start the extraction

•	Close the text file after VisitDataSection( ) has completed data extraction.

Sub VisitReportSection( obj As AcReportSection )

' Open output text file

Channel = FreeFile( )

Open FileName For Output As #Channel

' Write column labels

Print #Channel, "OfficeName,";

Print #Channel, "SalesRepName,";

Print #Channel, "ContactName,";

Print #Channel, "ContactPhone,";

Print #Channel, "CompanyName,";

Print #Channel, "CreditRank,";

Print #Channel, "PurchasingPattern,";

Print #Channel, "OrderNumber,";

Print #Channel, "ForecastOrderDate,";

Print #Channel, "NeededOrderDate,";

Print #Channel, "ForecastOrderShipDate,";

Print #Channel, "OrderStatus,";

Print #Channel, "ItemCategory,";

Print #Channel, "ItemDescription,";

Print #Channel, "ItemQuantity,";

Print #Channel, "ItemPrice,";

Print #Channel, "ItemExtendedPrice,";

Print #Channel

' Start data extraction from report object to outputtext file

VisitDataSection( obj )

' Close output text file and end processing after extraction is complete

Close #Channel

End Sub

3	Overrides VisitDataFrame( ) method to detect the kind of frame being visited and call a specialized subroutine to process the frame. In the example, special subroutines are created to extract data from each kind of frame, for example, CustomerTitleFrame or ItemFrame. The sample code for the VisitItemDetail subroutine is shown after the code that overrides the VisitDataFrame( ) method. The logic for the other kinds of frames is similar to the code in the VisitItemDetail subroutine.

' Map a generic data frame into one of the report-specific

' types.  Note that we use a Case statement

' here which is different than the way the Visitor handles

' AFC-provided classes.  The Case statement approach is

' slower at run time, but keeps data extraction code out

' of the report component classes.

Sub VisitDataFrame( obj As AcDataFrame )

Dim frameName	As String

Dim i	As Integer

frameName = GetClassName( obj )

i = Len( frameName )

Do While i > 1  And Mid$( frameName, i, 1 ) <> ":"

i = i - 1

Loop

If i > 1 Then

frameName = Mid$( frameName, i + 1 )

End If

Select Case frameName

Case "ReportTitle1"

VisitReportBefore( obj )

'Case "ReportTotals"

VisitReportAfter( obj )

Case "OfficeTitleFrame"

VisitOfficeTitleFrame( obj )

'Case "OfficeGroupTotals"

VisitOfficeGroupTotals( obj )

Case "SalesRepTitleFrame"

VisitSalesRepTitleFrame( obj )

'Case "SalesRepTotalsFrame"

VisitSalesRepTotalsFrame( obj )

Case "CustomerTitleFrame"

VisitCustomerTitleFrame( obj )

'Case "CustomerGroupTotals"

VisitCustomerGroupTotals( obj )

Case "OrderTitleFrame"

VisitOrderTitleFrame( obj )

'Case "OrderTotalsFrame"

VisitOrderTotalsFrame( obj )

Case "ItemFrame"

VisitItemDetail( obj )

End Select

End Sub

This code sample extracts data from the content frame, ItemFrame. The GetControlValue( ) function accesses the data control's DataValue property. TextField and NumericField are data extraction utility functions that convert the format of each control's value before writing the value to the output text file. The subroutines, TextField and NumericField are shown in the sample code for step 1.

Sub VisitItemDetail( frame As AcDataFrame )

ItemCategory = frame.GetControlValue( "ItemCategory" )

ItemCode = frame.GetControlValue( "ItemCode" )

ItemDescription = frame.GetControlValue( "ItemCategory" )

ItemQuantity = frame.GetControlValue( "IntegerControl" )

ItemPrice = frame.GetControlValue( "IntegerControl1" )

ItemExtension = frame.GetControlValue( "IntegerControl2" )

' Converts the control to the format required for the output text file

TextField( OfficeName )

TextField( RepName )

TextField( CustomerContactName )

TextField( CustomerContactPhone )

TextField( CustomerName )

TextField( CustomerCreditRank )

TextField( CustomerPurchPattern )

NumericField( OrderNumber )

TextField( OrderForecastDate1 )

TextField( OrderNeededDate )

TextField( OrderForecastDate2 )

TextField( OrderStatus )

TextField( ItemCategory )

TextField( ItemDescription )

NumericField( ItemQuantity )

NumericField( ItemPrice )

NumericField( ItemExtension )

' Writes converted field to output text file

Print #Channel

NeedComma = False

End Sub

4	Overrides visit methods to prevent processing for the following components: sequential, parallel, and conditional sections. The example application excludes these components from being processed by overriding the visit method for the excluded component and by not calling the superclass. The code sample shows how to prevent processing sequential sections.

Sub VisitSequentialSection( obj As AcSequentialSection )

End Sub

5	Defines an action (left-click mouse button) on the report control to start the data extraction utility. The example overrides the OnLButtonClick( ) method to perform the following tasks:

1	Instantiates the report's visitor class, AcDetailCsvVisitor

2	Sets the text output file name

3	Gets a reference to the location of the report object

4	Starts to traverse the content hierarchy

5	After data extraction is complete, the example starts Microsoft Excel and displays the spreadsheet.

Function OnLButtonClick( view As AcReportView, Shift As AcShiftKeyState, x As Integer, y As Integer ) As Boolean

    Dim visitor As AcDetailCsvVisitor

Set visitor = New AcDetailCsvVisitor

visitor.FileName = "c:\temp\extract.csv"

GetContainer( ).GetContainer( ).ApplyVisitor( visitor )

Shell( "d:\Program Files\Microsoft Office\Office\excel.exe c:\temp\extract.csv", 1 )

OnLButtonClick = True

End Function


Methods for class AcVisitor

AcVisitor::VisitBaseFrame method

AcVisitor::VisitBasePage method

AcVisitor::VisitComponent method

AcVisitor::VisitConditionalSection method

AcVisitor::VisitContents method

AcVisitor::VisitControl method

AcVisitor::VisitCurrencyControl method

AcVisitor::VisitDataControl method

AcVisitor::VisitDataFrame method

AcVisitor::VisitDataSection method

AcVisitor::VisitDateTimeControl method

AcVisitor::VisitDetailGraph method

AcVisitor::VisitDoubleControl method

AcVisitor::VisitEllipseControl method

AcVisitor::VisitFlow method

AcVisitor::VisitFrame method

AcVisitor::VisitFrameSetSection method

AcVisitor::VisitGraph method

AcVisitor::VisitGroupSection method

AcVisitor::VisitHLCGraph method

AcVisitor::VisitHtmlAppletControl method

AcVisitor::VisitHtmlImageControl method

AcVisitor::VisitHtmlObjectControl method

AcVisitor::VisitHtmlPlugInControl method

AcVisitor::VisitHtmlReport method

AcVisitor::VisitHtmlRuleControl method

AcVisitor::VisitHtmlTextFrame method

AcVisitor::VisitImageControl method

AcVisitor::VisitIntegerControl method

AcVisitor::VisitLabelControl method

AcVisitor::VisitLeftRightPageList method

AcVisitor::VisitLeftToRightFlow method

AcVisitor::VisitLinearFlow method

AcVisitor::VisitLineControl method

AcVisitor::VisitOleContainerControl method

AcVisitor::VisitOleControl method

AcVisitor::VisitPage method

AcVisitor::VisitPageList method

AcVisitor::VisitParallelSection method

AcVisitor::VisitRectangleControl method

AcVisitor::VisitReport method

AcVisitor::VisitReportSection method

AcVisitor::VisitSection method

AcVisitor::VisitSequentialSection method

AcVisitor::VisitSimplePageList method

AcVisitor::VisitSubpage method

AcVisitor::VisitSummaryGraph method

AcVisitor::VisitTextControl method

AcVisitor::VisitTitleBodyPageList method

AcVisitor::VisitTopDownFlow method

AcVisitor::VisitVisualComponent method


AcVisitor::VisitBaseFrame method

Syntax

Function VisitBaseFrame( ) As AcBaseFrame

Description

Visit the AcBaseFrame component.


AcVisitor::VisitBasePage method

Syntax

Function VisitBasePage( ) As AcBasePage

Description

Visit the AcBasePage component.


AcVisitor::VisitComponent method

Visit the components of a report.

Syntax

Function VisitComponent( ) as AcReportComponent

Description

Visit a report's component.


AcVisitor::VisitConditionalSection method

Syntax

Function VisitConditionalSection( ) As AcConditionalSection.

Description

Visit the AcConditionalSection component.


AcVisitor::VisitContents method

Visit the contents of a report's data hierarchy components.

Syntax

Function VisitContents( ) As AcReportComponent

Description

Use the VisitContents( ) method to recursively traverse all the components that comprise a report's data hierarchy. VisitContents( ) uses the AcIterator class methods to traverse the data hierarchy. VisitContents( ) calls ApplyVisitor( ) for each component in the data hierarchy.


AcVisitor::VisitControl method

Syntax

Function VisitControl( ) As AcControl

Description

Visit the AcControl component.


AcVisitor::VisitCurrencyControl method

Syntax

Function VisitCurrencyControl( ) As AcCurrencyControl

Description

Visit the AcCurrencyControl component.


AcVisitor::VisitDataControl method

Syntax

Function VisitDataControl( ) As AcDataControl

Description

Visit the AcDataControl component.


AcVisitor::VisitDataFrame method

Example

Syntax

Function VisitDataFrame( ) As AcDataFrame

Description

Visit the AcDataFrame component.


Example

This code sample overrides the VisitDataFrame( ) method to extract the contents of three different frames in the report object: OfficeTitleFrame, OfficeGroupTotals, and OfficeFrame. The GetClassName( ) function returns the name of the frame being visited. Then, a specialized subroutine that knows about the contents of the frame is called to perform the extraction.

' Map a generic data frame into one of the report-specific

' types handled above.  Note that we use a Case statement

' here which is different than the way the Visitor handles

' AFC-provided classes.  The case statement approach is

' slower at run time, but keeps data extraction code out

' of the report component classes.

Sub VisitDataFrame( obj As AcDataFrame )

Dim frameName	As String

Dim i	As Integer

frameName = GetClassName( obj )

i = Len( frameName )

Do While i > 1  And Mid$( frameName, i, 1 ) <> ":"

i = i - 1

Loop

If i > 1 Then

frameName = Mid$( frameName, i + 1 )

End If

Select Case frameName

Case "OfficeTitleFrame"

VisitOfficeTitleFrame( obj )

'Case "OfficeGroupTotals"

VisitOfficeGroupTotals( obj )

Case "OfficeFrame"

VisitOfficeFrame( obj )

End Select

End Sub


AcVisitor::VisitDataSection method

Syntax

Function VIsitDataSection( ) As AcDataSection

Description

Visit the AcDataSection component.


AcVisitor::VisitDateTimeControl method

Syntax

Function VisitDateTimeControl( ) As AcDateTimeControl

Description

Visit the AcDateTimeControl component.


AcVisitor::VisitDetailGraph method

Syntax

Function VisitDetailGraph( ) As AcDetailGraph

Description

Visit the AcDetailGraph component.


AcVisitor::VisitDoubleControl method

Syntax

Function VisitDoubleControl( ) As AcDoubleControl

Description

Visit the AcDoubleControl component.


AcVisitor::VisitEllipseControl method

Syntax

Function VisitEllipseControl( ) As AcEllipseControl

Description

Visit the AcEllipseControl component.


AcVisitor::VisitFlow method

Syntax

Function VisitFlow( ) As AcFlow

Description

Visit the AcFlow component.


AcVisitor::VisitFrame method

Syntax

Function VisitFrame( ) As AcFrame

Description

Visit the AcFrame component.


AcVisitor::VisitFrameSetSection method

Syntax

Function VisitFrameSetSection( ) As AcFrameSetSection

Description

Visit the AcFrameSetSection component.


AcVisitor::VisitGraph method

Syntax

Function VisitGraph( ) As AcGraph

Description

Visit the AcGraph component.


AcVisitor::VisitGroupSection method

Syntax

Function VisitGroupSection( ) As AcGroupSection

Description

Visit the AcGroupSection component.


AcVisitor::VisitHLCGraph method

Syntax

Function VisitHLCGraph( ) As AcHLCGraph

Description

Visit the AcHLCGraph component.


AcVisitor::VisitHtmlAppletControl method

Syntax

Function VisitHtmlAppletControl( ) As AcHtmlAppletControl

Description

Visit the AcHtmlAppletControl component.


AcVisitor::VisitHtmlImageControl method

Syntax

Function VisitHtmlImageControl( ) As AcHtmlImageControl

Description

Visit the AcHtmlImageControl component.


AcVisitor::VisitHtmlObjectControl method

Syntax

Function VisitHtmlObjectControl( ) As AcHtmlObjectControl

Description

Visit the AcHtmlObjectControl component.


AcVisitor::VisitHtmlPlugInControl method

Syntax

Function VisitHtmlPlugInControl( ) As AcHtmlPlugInControl

Description

Visit the AcHtmlPlugInControl component.


AcVisitor::VisitHtmlReport method

Syntax

Function VisitHtmlReport( ) As AcHtmlReport

Description

Visit the HtmlReport component.


AcVisitor::VisitHtmlRuleControl method

Syntax

Function VisitHtmlRuleControl( ) As AcHtmlRuleControl

Description

Visit the AcHtmlRuleControl component.


AcVisitor::VisitHtmlTextFrame method

Syntax

Function VisitHtmlTextFrame( ) As AcHtmlTextFrame

Description

Visit the HtmlTextFrame component.


AcVisitor::VisitImageControl method

Syntax

Function VisitImageControl( ) As AcImageControl

Description

Visit the AcImageControl component.


AcVisitor::VisitIntegerControl method

Syntax

Function VisitIntegerControl( ) As AcIntegerControl

Description

Visit the AcIntegerControl component.


AcVisitor::VisitLabelControl method

Syntax

Function VisitLabelControl( ) As AcLabelControl

Description

Visit the AcLabelControl component.


AcVisitor::VisitLeftRightPageList method

Syntax

Function LeftRightPageList( ) As AcLeftRightPageList

Description

Visit the AcLeftRightPageList component.


AcVisitor::VisitLeftToRightFlow method

Syntax

Function VisitLeftToRightFlow( ) As AcLeftToRightFlow

Description

Visit the AcLeftToRightFlow component.


AcVisitor::VisitLinearFlow method

Syntax

Function VisitLinearFlow( ) As AcLinearFlow

Description

Visit the AcLinearFlow component.


AcVisitor::VisitLineControl method

Syntax

Function VisitLineControl( ) As AcLineControl

Description

Visit the AcLineControl component.


AcVisitor::VisitOleContainerControl method

Syntax

Function VisitOleContainerControl( ) As AcOleContainerControl

Description

Visit the AcOleContainerControl component.


AcVisitor::VisitOleControl method

Syntax

Function VisitOleControl( ) As AcOleControl

Description

Visit the AcOleControl component.


AcVisitor::VisitPage method

Syntax

Function VisitPage( ) As AcPage

Description

Visit the AcPage component.


AcVisitor::VisitPageList method

Syntax

Function VisitPageList( ) As AcPageList

Description

Use the VisitPageList( ) method to recursively traverse all the components that comprise a report's page hierarchy. VisitPageList( ) uses the AcIterator class methods to traverse the page hierarchy. VisitPageList( ) calls ApplyVisitor( ) for each component in the page hierarchy.


AcVisitor::VisitParallelSection method

Syntax

Function VisitParallelSection( ) As AcParallelSection

Description

Visit the AcParallelSection component.


AcVisitor::VisitRectangleControl method

Syntax

Function VisitRectangleControl( ) As AcRectangleControl

Description

Visit the AcRectangleControl component.


AcVisitor::VisitReport method

Syntax

Function VisitReport( ) As AcReport

Description

Visit the report component.


AcVisitor::VisitReportSection method

Syntax

Function VisitReportSection( ) As AcReportSection

Description

Visit the AcReportSection component.


AcVisitor::VisitSection method

Syntax

Function VisitSection( ) As AcSection

Description

Visit the AcSection component.


AcVisitor::VisitSequentialSection method

Syntax

Function VisitSequentialSection( ) As AcSequentialSection

Description

Visit the AcSequentialSection component.


AcVisitor::VisitSimplePageList method

Syntax

Function VisitSimplePageList( ) As AcSimplePageList

Description

Visit the AcSimplePageList component.


AcVisitor::VisitSubpage method

Syntax

Function VisitSubpage( ) As AcSubpage

Description

Visit the AcSubpage component.


AcVisitor::VisitSummaryGraph method

Syntax

Function VisitSummaryGraph( ) As AcSummaryGraph

Description

Visit the AcSummaryGraph component.


AcVisitor::VisitTextControl method

Syntax

Function VisitTextControl( ) As AcTextControl

Description

Visit the AcTextControl component.


AcVisitor::VisitTitleBodyPageList method

Syntax

Function VisitTitleBodyPageList( ) As AcTitleBodyPageList

Description

Visit the AcTitleBodyPageList component.


AcVisitor::VisitTopDownFlow method

Syntax

Function VisitTopDownFlow( ) As AcTopDownFlow

Description

Visit the AcTopDownFlow component.


AcVisitor::VisitVisualComponent method

Syntax

Function VisitVisualComponent( ) As AcVisualComponent

Description

Visit the VisualComponent component.


Class AcVisualComponent

See also   Methods

AcVisualComponent is the base class for all classes whose objects are visual.

Description

AcVisualComponent defines the characteristics common to all visual objects in a report. A report's visual objects are

•	Frames

•	Graphs

•	Controls

•	Pages

•	Flows

The two primary characteristics that AcVisualComponent adds to those it inherits from AcReportComponent are

•	Visual attributes, such as position and size.

•	Interactive attributes that specify how users can interact with visual objects in the Viewer. AcVisualComponent defines methods that let you control the following events when users view and interact with the report.

•	Mouse events

•	Hyperlinks

•	Context-sensitive help

•	Context menu

AcVisualComponent also defines a property, ObjectVariable, that enables access to visual objects. When you assign a value to ObjectVariable, the framework generates a function to access the object. For example, if you set a control's ObjectVariable property to MyControl, the frame that contains that control provides a function called myControl( ) to access the control. The following statement is an example of how you access and modify the control through code that you write for the containing frame:

MyControl.BackgroundColor = Teal

You can access the control only from its containing frame, not from another control. When you assign a value to ObjectVariable, do not use the name of an existing method. If you do so, a compile time error occurs.

Subclassing AcVisualComponent

Do not subclass from AcVisualComponent. Rather, subclass from classes derived from AcVisualComponent, such as AcControl, AcFrame, and so on.

Variables

Variable	Type	Description
Position	AcPoint	The x,y coordinates, in twips, that specify the location of the object relative to the top-left corner of its container object.
Size	AcSize	The height and width of the object in twips. If the object is a circle or a line, the object's size is the size of the box that bounds it.
LinkTo	String	The value of the hyperlink, defined in the LinkExp property.
Properties

Property	Type	Description
CursorShape	AcCursorShape	The kind of cursor to show when the mouse cursor passes over the object.
HelpText	String	The text to show for this object when the user asks for help.
LinkExp	String	The expression defining a hyperlink for this object.
ObjectVariable	Value	The name of an optional method in the frame that will point to this object.
Position	AcPosition	The position of the object in its enclosing frame.
Searchable	Boolean	Specifies if the object can be searched in the Viewer.
SearchAlias	String	The name to display to the user when building a search for this object.
Selectable	Boolean	True if the user can select this object in the Viewer.
Size	AcSize	The size of the visual object.
TargetWindowName	String	The name of a target window in which the contents of a hyperlink should appear.
Methods

Method	Type	Description
AddMenuCommands( )	N/A	Builds the context menu that appears when users press the right mouse button.
CursorShape( )	AcCursor Shape	Implements the CursorShape property.
GetBottom( )	Integer	Returns the bottom position of the component.
GetFrame( )	AcFrame	Returns a reference to the frame containing the visual object.
GetHeight( )	Integer	Returns the height of the component.
GetHtmlLinkTo()	String	Returns the HTML value of the hyperlink expression contained in the LinkTo variable.
GetLeft( )	Integer	Returns the left position of the component.
GetLinkTo()	String	Returns value of the hyperlink expression contained in the LinkTo variable.
GetPage	AcBase Frame	Returns the page on which this frame appears.
GetRight( )	Integer	Returns the right position of the component.
GetTop( )	Integer	Returns the top position of the component.
GetWidth( )	Integer	Returns the width of the component.
HelpText( )	String	Implements the HelpText property.
MoveBy( )	N/A	Moves the component by the amount given.
MoveTo( )	N/A	Moves the component to the position given.
OnActuate( )	Boolean	A placeholder method that you override to implement a visual object's main task.
OnContextMenu( )	Boolean	Displays a context menu that appears when users press the right mouse button.
OnFollowLink( )	Boolean	Override to implement a hyperlink.
OnHelp( )	Boolean	Displays the HelpText string.
OnLButtonClick( )	Boolean	Called on a left button click.
OnLButtonDblClk( )	Boolean	Called on a left button double click.
OnLButtonDown( )	Boolean	Called on a left button down event.
OnLButtonUp( )	Boolean	Called on a left button up event.
OnRButtonClick( )	Boolean	Called on a right button click.
OnRButtonDblClk( )	Boolean	Called on a right button double click.
OnRButtonDown( )	Boolean	Called on a right button down event.
OnRButtonUp( )	Boolean	Called on a right button up event.
ResizeBy( )	N/A	Resizes a component by the distances given.
ResizeTo( )	N/A	Resizes a frame or control to the given size.
Searchable( )	Boolean	Implements the Searchable property.
SearchAlias( )	String	Implements the SearchAlias property.
Selectable( )	Boolean	Implements the Selectable property.
ShowInHTML( )	Boolean	Determines whether or not the control is visible on the HTML report. Default is True.
ShowWhenPrinting( )	Boolean	Determines whether or not the control is visible in the printed report. Default is True.
ShowWhenViewing( )	Boolean	Determines whether or not the control is visible when viewing the report. Default is True.
StatusText( )	String	Returns the value of GetLinkTo( ) if there is a hyperlink, or HelpText( ) otherwise.


See also

Class AcControl

Class AcFrame

Class AcGraph

Class AcReportComponent


Methods for class AcVisualComponent

AcVisualComponent::AddMenuCommands method

AcVisualComponent::CursorShape method

AcVisualComponent::GetBottom method

AcVisualComponent::GetFrame method

AcVisualComponent::GetHeight method

AcVisualComponent::GetHtmlLinkTo

AcVisualComponent::GetLeft method

AcVisualComponent::GetLinkTo method

AcVisualComponent::GetPage method

AcVisualComponent::GetRight method

AcVisualComponent::GetTop method

AcVisualComponent::GetWidth method

AcVisualComponent::HelpText method

AcVisualComponent::MoveBy method

AcVisualComponent::MoveTo method

AcVisualComponent::OnActuate method

AcVisualComponent::OnContextMenu method

AcVisualComponent::OnFollowLink method

AcVisualComponent::OnHelp method

AcVisualComponent::OnLButtonClick method

AcVisualComponent::OnLButtonDblClk method

AcVisualComponent::OnLButtonDown method

AcVisualComponent::OnLButtonUp method

AcVisualComponent::OnRButtonClick method

AcVisualComponent::OnRButtonDblClk method

AcVisualComponent::OnRButtonDown method

AcVisualComponent::OnRButtonUp method

AcVisualComponent::ResizeBy method

AcVisualComponent::ResizeTo method

AcVisualComponent::Searchable method

AcVisualComponent::SearchAlias method

AcVisualComponent::Selectable method

AcVisualComponent::StatusText method


AcVisualComponent::AddMenuCommands method

See also

Builds the context menu that appears when the user presses the right mouse button.

Syntax

Sub AddMenuCommands( menu As AcPopupMenu )

menu

A reference to the pop-up menu.

Description

By default, AddMenuCommands( ) creates a context menu with the following two items:

•	Default Action executes OnActuate( ) when users choose this menu item.

•	Help executes OnHelp( ) when users choose this menu item.

In a derived class, you can override AddMenuCommands( ) to change the default items and add new ones.

Example

This code sample overrides the AddMenuCommands( ) method on a control in a report to add two menu items to the context menu. The menu items allow the user to jump to different reports. The report object contains a summary report for the United States and detail and summary reports for each region within the United States. From the US summary report, the user is able to right-click on a region to view a context menu showing items for the region's summary and detail reports. Then, the user can select the type of report and jump directly to it.

The Actuate Basic Case statement is used to examine the DataValue property of the region control and a menu item for the summary report and one for the detail report. Two user-defined methods, LinkToDetail and LinkToSummary, have been written to change the region control's LinkExp property and cause the jump to the selected report. To see how this is done, see AcVisualComponent::OnFollowLink method.

The AddSeparator( ) method is called to add a separator line between the added items and the other menu items.

Sub AddMenuCommands( menu As AcPopupMenu )

' The Actuate Basic Case statement is used to test the DataValue property

' of the selected region control in the report. Two menu items are added

' based on the DataValue property. For example, if the DataValue is

' East' then a items Eastern Summary and Eastern Detail are added.

' The AddItem method on AcPopUpMenu class is used to add the menu

' items. LinkToSummary and LinkToDetail are user-defined methods on the

' region control class.

Select Case DataValue

Case "East"

menu.AddItem( "Eastern Summary", me, "LinkToSummary" )

menu.AddItem( "Eastern Detail", me, "LinkToDetail")

Case "West"

'menu.AddItem( "Western Summary", me, "LinkToSummary" )

menu.AddItem( "Western Detail", me, "LinkToDetail")

Case "South"

'menu.AddItem( "Southern Summary", me, "LinkToSummary" )

menu.AddItem( "Southern Detail", me, "LinkToDetail")

Case "North"

'menu.AddItem( "Northern Summary", me, "LinkToSummary" )

menu.AddItem( "Northern Detail", me, "LinkToDetail")

End Select

Add a separator line after the new menu items

    menu.AddSeparator ()

    Super::AddMenuCommands( menu )

End Sub


See also

AcVisualComponent::OnActuate method

AcVisualComponent::OnContextMenu method

AcVisualComponent::OnHelp method

AcVisualComponent::HelpText method

Class AcPopupMenu


AcVisualComponent::CursorShape method

See also

Implements the CursorShape property that appears in the Properties page of the Component Editor.

Syntax

Function CursorShape( ) As AcCursorShape

Description

CursorShape specifies the type of cursor to display when the mouse pointer moves over the object.

Default

•	The standard arrow cursor when the object is not selectable.

•	The active arrow cursor when the object is selectable.


See also

AcVisualComponent::Selectable method


AcVisualComponent::GetBottom method

Returns the position of the bottom of the component.

Syntax

Function GetBottom( ) As Integer

Description

Returns the position of the bottom of the component (in twips) relative to the top of its enclosing frame.


AcVisualComponent::GetFrame method

Returns a reference to the frame containing the visual object.

Syntax

Function GetFrame( ) As AcFrame

Description

A visual object is typically contained in a frame. In a derived class, you can call GetFrame( ) to find out which frame contains the current object.

Return value

A reference to the frame if the current object is a control.

A reference to itself if the current object is a frame.


AcVisualComponent::GetHeight method

Returns the height of the component.

Syntax

Function GetHeight( ) As Integer

Description

Returns the height of the component in twips.


AcVisualComponent::GetHtmlLinkTo

Returns the value of the LinkTo variable in HTML format.

Syntax

Function GetHtmlLinkTo( ) As String

Description

Returns the value of the hyperlink contained in the LinkTo variable in HTML format. The LinkTo variable's value is generated from the LinkExp expression property.


AcVisualComponent::GetLeft method

Returns the position of the left edge of the component.

Syntax

Function GetLeft( ) As Integer

Description

Returns the position of the left edge of the component (in twips) relative to the left edge of its enclosing frame.


AcVisualComponent::GetLinkTo method

Returns the value of the hyperlink expression contained in the LinkTo variable.

Syntax

Function GetLinkTo( ) As String

Description

Returns the value of the hyperlink expression contained in the LinkTo variable. The LinkTo variable's value is generated from the LinkExp expression property.


AcVisualComponent::GetPage method

Returns the page on which this frame or control appears.

Syntax

Function GetPage( ) As AcBaseFrame

Description

The GetPage( ) method is a utility function intended primarily for use in the Viewer. Call this method to find out the page on which this frame or control appears.

If you use this method within the Factory, you must be aware of when the page becomes available. A frame is assigned to a page by its enclosing section after the section finishes the frame. While building the frame with the Start( ), Build( ), BuildFromRow( ), or Finish( ) methods, the frame is not yet assigned to a page, so this method returns Nothing. The reason is that you might choose to adjust the frame size as part of the Finish( ) processing. As a result, the framework does not know if the frame will fit on the current page or whether a new page will be needed until after the frame is completely finished.

Return value

A reference to the page on which this frame or control appears.

Nothing if the frame has not yet been assigned to a page by the Factory.


AcVisualComponent::GetRight method

Returns the position of the right edge of the component.

Syntax

Function GetRight( ) As Integer

Description

Returns the position of the right edge of the component (in twips) relative to the left edge of its enclosing frame.


AcVisualComponent::GetTop method

Returns the position of the top of the component.

Syntax

Function GetTop( ) As Integer

Description

Returns the position of the top of the component (in twips) relative to the top of its enclosing frame.


AcVisualComponent::GetWidth method

Returns the width of the component.

Syntax

Function GetWidth( ) As Integer

Description

Returns the width of the component in twips.


AcVisualComponent::HelpText method

See also

Implements the HelpText property.

Syntax

Function HelpText( ) As String

Description

HelpText specifies the string to display for the selected object in the Viewer. The help string appears when OnHelp( ) executes. By default, OnHelp( ) is called by AddMenuCommands( ), which builds the context menu. Help is, therefore, accessible through the default context menu.

The following figure illustrates the default sequence of method calls leading to HelpText( ).

Default

"There is no help for this item."


See also

AcVisualComponent::AddMenuCommands method

AcVisualComponent::OnHelp method


AcVisualComponent::MoveBy method

See also

Moves a control or frame.

Syntax

Sub MoveBy( deltaX As Integer, deltaY As Integer )

deltaX

The horizontal distance (in twips) relative to the current position to move the component.

deltaY

The vertical distance (in twips) relative to the current position to move the component.

Description

The MoveBy( ) method moves a control or nested frame within its enclosing frame or flow by the distances given. The distances can be positive or negative.


See also

AcVisualComponent::MoveTo method


AcVisualComponent::MoveTo method

See also

Changes the position of a control or nested frame.

Syntax

Sub MoveTo( newX As Integer, newY As Integer )

newX

New X-position of the control, in twips, relative to the left edge of the enclosing frame.

newY

New Y-position of the control, in twips, relative to the top edge of the enclosing frame.

Description

The MoveTo( ) method changes the position of a control or nested frame within its enclosing frame or flow.


See also

AcVisualComponent::MoveBy method


AcVisualComponent::OnActuate method

See also

Override to implement the visual object's main task.

Syntax

Function OnActuate( view As AcReportView, x As Integer, y As Integer ) As Boolean

view

The window the report is in.

x

The horizontal position of the mouse cursor at the time of the event, measured in pixels relative to the left of the view.

y

The vertical position of the mouse cursor at the time of the event, measured in pixels relative to the top of the view.

Description

By default, OnActuate( ) executes OnFollowLink( ). OnFollowLink( ) implements hyperlinks between objects.

In Windows applications, double clicking items typically executes the main action. Following this convention, OnLButtonDblClk( ), which executes when the user double clicks the left mouse button, calls OnActuate(  ). OnActuate( ) is also called by AddMenuCommands( ) so that the main task is accessible from the context menu as well.

The following figure illustrates the default sequence of method calls.

In derived classes, override OnActuate( ) to specify a visual object's default action. For example, the default action for a video control would be to play a video clip, and the code to do so should be in OnActuate( ).

If you want other event methods, such as OnRButtonClick( ) or OnLButtonClick( ), to perform the main task, call OnActuate( ) from those other methods.

Return value

True if the event is handled by the current object.

False if the event is not handled by the current object.


See also

AcVisualComponent::AddMenuCommands method

AcVisualComponent::OnFollowLink method

AcVisualComponent::OnLButtonDblClk method


AcVisualComponent::OnContextMenu method

See also

Displays the context menu that appears when users press the right mouse button.

Syntax

Function OnContextMenu( view As AcReportView, x As Integer,
y As Integer ) As Boolean

view

The window the report is in.

x

The horizontal position of the mouse cursor at the time of the event, measured in pixels relative to the left of the view.

y

The vertical position of the mouse cursor at the time of the event, measured in pixels relative to the top of the view.

Description

By default, OnContextMenu( ) displays a context menu whose content is built by calling AddMenuCommands( ). You specify the menu items to display by overriding AddMenuCommands( ).

In many Windows applications, pressing the right mouse button typically displays a context menu. Following this convention, OnRButtonDown( ), which executes when the user presses the right mouse button, calls OnContextMenu(  ). The following figure illustrates the default sequence of method calls.

In derived classes, you can override OnContextMenu( ) to add further processing. Typically, however, you use OnContextMenu( ) as designed, and override AddMenuCommands( ) to specify the menu items to display and corresponding actions to execute.

Return value

True if the event is handled by the current object.

False if the event is not handled by the current object.


See also

AcVisualComponent::AddMenuCommands method

AcVisualComponent::OnRButtonDown method


AcVisualComponent::OnFollowLink method

See also

A placeholder method that implements hyperlinks between objects.

Syntax

Function OnFollowLink( view As AcReportView, x As Integer, y As Integer ) As Boolean

view

The window the report is in.

x

The horizontal position of the mouse cursor at the time of the event, measured in pixels relative to the left of the view.

y

The vertical position of the mouse cursor at the time of the event, measured in pixels relative to the top of the view.

Description

By default, OnFollowLink( ) does nothing. Derived classes override this method to implement the hyperlink navigation logic.

OnActuate( ) calls OnFollowlink( ) by default. Therefore, when users double-click with the left mouse button, OnFollowLink( ) executes.

The following figure illustrates the default sequence of method calls leading to OnFollowLink( ).

If you want other event methods, such as OnRButtonClick( ) or OnLButtonClick( ), to trigger OnFollowLink( ), call OnFollowLink( ) from those methods.

For an example showing how to override OnFollowLink( ) to establish a hyperlink to another report, see Chapter 10, "Programming for report viewing events," in Programming with Actuate.

Return value

True if the event is handled by the current object.

False if the event is not handled by the current object.

Example

This code example calls the OnFollowLink( ) method to jump from a national summary report to a regional summary or detail report. In the national summary report, the user can jump to either report from the context menu for the region control. The context menu has been dynamically changed using the AddMenuCommands( ) method. Additional items for the regional detail report or regional summary report appear on the context menu. To see how the menu items are added, see AcVisualComponent::AddMenuCommands method.

The example subroutine, LinkToDetail, uses the Actuate Basic Case statement to examine the DataValue property of the region control and set the control's LinkExp property based on the outcome of the test. OnFollowLink( ) is called to jump to the selected report using the region control's LinkTo property. A subroutine, LinkToSummary, uses similar logic to jump to the regional summary report.

Sub LinkToDetail( )

' The Actuate Basic Case statement examines the DataValue property of the

' region control to set up the LinkTo property of the control. The LinkTo

' property contains the relative path to the report object instance.

Select Case DataValue

Case "East"

LinkTo = "Sales East/East Forecast Detail.roi"

Case "North"

LinkTo = "Sales North/North Forecast Detail.roi"

Case "South"

LinkTo = "Sales South/South Forecast Detail.roi"

Case "West"

LinkTo = "Sales West/West Forecast Detail.roi"

End Select

'The LinkTo property is used by OnFollowLink() to jump to the report.

    OnFollowLink ()

End Sub


See also

AcVisualComponent::AddMenuCommands method

AcVisualComponent::OnActuate method

AcVisualComponent::OnLButtonDblClk method


AcVisualComponent::OnHelp method

See also

Displays the string specified in HelpText.

Syntax

Function OnHelp( view As AcReportView, x As Integer, y As Integer ) As Boolean

view

The window the report is in.

x

The horizontal position of the mouse cursor at the time of the event, measured in pixels relative to the left of the view.

y

The vertical position of the mouse cursor at the time of the event, measured in pixels relative to the top of the view.

Description

OnHelp( ) and HelpText( ) work together to specify how Actuate displays information about an object. By default, OnHelp( ) is called by AddMenuCommands( ), which builds the context menu. Help is, therefore, accessible through the default context menu. When users choose the Help menu item in the context menu, the help string specified in HelpText appears at the location where the mouse was clicked.

The following figure illustrates the default sequence of method calls leading to HelpText( ).

In derived classes, you can override OnHelp( ) to add further processing. Typically, however, you use OnHelp( ) as designed and override AddMenuCommands( ) to specify the menu items to display and corresponding actions to execute. You can also call OnHelp from another mouse event method if you want to provide another way to access help.

Return value

True if the event is handled by the current object.

False if the event is not handled by the current object.


See also

AcVisualComponent::AddMenuCommands method

AcVisualComponent::HelpText method

AcVisualComponent::OnContextMenu method

AcVisualComponent::OnRButtonDown method


AcVisualComponent::OnLButtonClick method

See also

Executes when users click the left mouse button on a visual object.

Syntax

Function OnLButtonClick( view As AcReportView, Shift As AcShiftKeyState,
x As Integer, y As Integer ) As Boolean

view

The window the report is in.

Shift

A bit field that indicates if the Shift, Ctrl, or Alt keys were pressed at the time of the event. Shift can contain one of the following values:

Keys pressed	Bit value	Shift value
None	0	NoKeys
Shift	1	ShiftKey
Ctrl	2	ControlKey
Shift + Ctrl	3	Both ShiftKey and ControlKey
Alt	4	AltKey
Shift + Alt	5	Both ShiftKey and AltKey
Ctrl + Alt	6	Both CtrlKey and AltKey
x

The horizontal position of the mouse cursor at the time of the event, measured in pixels relative to the left of the view.

y

The vertical position of the mouse cursor at the time of the event, measured in pixels relative to the top of the view.

Description

By default, OnLButtonClick( ) does nothing. It returns False if the event is not handled.

In derived classes, you can override OnLButtonClick( ) to perform a task when users press and release the left mouse button on a single object. If you need to execute different actions, depending on whether the left mouse button is down or up, use OnLButtonDown( ) or OnLButtonUp( ) instead.

Using the Shift values, you can assign different actions to the different key and left mouse click combinations. You can also use the x- and y-coordinates to execute different actions, depending on where the left mouse click event occurred. This technique is particularly useful for graphs where you might want to display something different depending on the region of the graph that was clicked.

Example

This example shows how to override the OnLButtonClick( ) method to handle several interactive report display actions such as modifying the appearance of controls and refreshing the report display.

The example application displays sales statistics in the monetary unit selected by the user at runtime. Then, the user can have the report re-calculated and displayed in another monetary unit by selecting a report control. The user is presented with three selectable controls, TextControl, TextControl1, and TextControl2, to cause the report's monetary controls to be displayed in either US dollars, French Francs, or German Deutschmarks. The background color of the selected control is set to light gray and the background color of the other controls is set to transparent.

Function OnLButtonClick( view As AcReportView, Shift As AcShiftKeyState, x As Integer, y As Integer ) As Boolean

Dim theLink As AcReportController

' Set up object reference variables for frame and selectable controls

Dim aFrame As AcFrame

Dim USDTC As AcTextControl

Dim FFTC As AcTextControl

Dim DMTC As AcTextControl

' Get frame location

Set aFrame = GetContainer()

' Get location for each selectable control

Set USDTC = FindContentByClass("NewReportApp::Frame2::TextControl")

Set FFTC = FindContentByClass("NewReportApp::Frame2::TextControl1")

Set DMTC = FindContentByClass("NewReportApp::Frame2::TextControl2")

' Change background of controls to emphasize selected control

USDTC.BackgroundColor = TransparentColor

FFTC.BackgroundColor = LightGray

DMTC.BackgroundColor = TransparentColor

' Get access to Report Controller methods so you can issue Viewer

' commands to refresh pages

Set theLink = New AcReportController

theLink.AttachToThisReport( )

' Refresh the page -- calls GetText( ) method for controls

theLink.ShowNextPage()

theLink.ShowPrevPage()

Set return code to indicate that the event has been handled

    OnLButtonClick = True

End Function

When the Actuate Viewer refreshes the display, the GetText( ) method for every control is called. In this override to the GetText( ) method, the currency control's value is re-calculated based on the monetary unit selected by the user.

Function GetText( ) As String

Dim returnStr As String

Dim lenOfStr As Integer

Dim i As Double

Tests monetary unit selected by user; 0=Dollars 1=Francs 2=Marks

If NewReportApp::gVar = 1 Then

   	returnStr = Super::GetText( )

i = CDbl(returnStr)

i = i * mFFRate

GetText = "FF " & CStr(i)

ElseIf NewReportApp::gVar = 2 Then

   	returnStr = Super::GetText( )

i = CCur(returnStr)

i = i * mDMRate

returnStr = CStr(i)

GetText = "DM " & returnStr

Else

GetText = "$ " & Super::GetText

End If

End Function

Return value

True if the event is handled by the current object.

False if the event is not handled.


See also

AcVisualComponent::OnLButtonDblClk method

AcVisualComponent::OnLButtonDown method

AcVisualComponent::OnLButtonUp method


AcVisualComponent::OnLButtonDblClk method

See also

Executes when users double click the left mouse button on a visual object.

Syntax

Function OnLButtonDblClk( view As AcReportView, Shift As AcShiftKeyState, x As Integer, y As Integer ) As Boolean

view

The window the report is in.

Shift

A bit field that indicates if the Shift, Ctrl, or Alt keys were pressed at the time of the event. See OnLButtonClick for the codes.

x

The horizontal position of the mouse cursor at the time of the event, measured in pixels relative to the left of the view.

y

The vertical position of the mouse cursor at the time of the event, measured in pixels relative to the top of the view.

Description

By default, OnLButtonDblClk( ) calls OnActuate( ) to execute the object's default action. For example, the default action for a video control would be to play a video clip, and the code to do so should be in OnActuate( ).

In derived classes, you can override OnLButtonDblClk( ) to perform a different task or to add functionality.

Using the Shift values, you can assign different actions to the different key and left double-click combinations. You can also use the x- and y-coordinates to execute different actions, depending on where the left double click event occurred. This technique is useful for graphs where you might want to do something different depending on the region of the graph that was double clicked.

Return value

True if the event is handled by the current object.

False if the event is not handled.


See also

AcVisualComponent::OnLButtonDblClk method

AcVisualComponent::OnLButtonDown method

AcVisualComponent::OnLButtonUp method


AcVisualComponent::OnLButtonDown method

See also

Executes when the user presses down the left mouse button.

Syntax

Function OnLButtonDown( view As AcReportView, Shift As AcShiftKeyState, x As Integer, y As Integer ) As Boolean

view

The window the report is in.

Shift

A bit field that indicates if the Shift, Ctrl, or Alt keys were pressed at the time of the event. See OnLButtonClick for the codes.

x

The horizontal position of the mouse cursor at the time of the event, measured in pixels relative to the left of the view.

y

The vertical position of the mouse cursor at the time of the event, measured in pixels relative to the top of the view.

Description

The default implementation of OnLButtonDown( ) defines the following actions:

User action	OnLButtonDown action
Press left mouse button on object.	Select the object and deselect other objects, if any were previously selected.
Press left mouse button and Shift key on object.	Select the object, adding it to the set of previously selected objects, if any.
Press left mouse button and Ctrl key on object.	Toggle the selection state of the object.
Press left mouse button and Shift + Ctrl keys on object.	Toggle the selection state of the object.

In derived classes, you can override OnLButtonDown( ) to add further processing. Typically, however, use OnLButtonDown( ) as designed to perform the conventional actions.

Return value

True if the event is handled by the current object.

False if the event is not handled.


See also

AcVisualComponent::OnLButtonDblClk method

AcVisualComponent::OnLButtonClick method

AcVisualComponent::OnLButtonUp method


AcVisualComponent::OnLButtonUp method

See also

Executes when users release the left mouse button on a visual object.

Syntax

Function OnLButtonUp( view As AcReportView, Shift As AcShiftKeyState,
x As Integer, y As Integer ) As Boolean

view

The window the report is in.

Shift

A bit field that indicates if the Shift, Ctrl, or Alt keys were pressed at the time of the event. See OnLButtonClick for the codes.

x

The horizontal position of the mouse cursor at the time of the event, measured in pixels relative to the left of the view.

y

The vertical position of the mouse cursor at the time of the event, measured in pixels relative to the top of the view.

Description

By default, OnLButtonUp( ) does nothing. It returns False if the event is not handled.

In derived classes, you can override OnLButtonUp( ) to perform a task when users release the left mouse button. If you need to execute an action when the left mouse button is down, use OnLButtonDown( ).

Using the Shift values, you can assign different actions to the different key and left mouse up combinations. You can also use the x- and y-coordinates to execute different actions, depending on where the left mouse up event occurred. This technique is particularly useful for graphs where you might want to do something different depending on the region of the graph.

Return value

True if the event is handled by the current object.

False is not handled.


See also

AcVisualComponent::OnLButtonClick method

AcVisualComponent::OnLButtonDblClk method

AcVisualComponent::OnLButtonDown method


AcVisualComponent::OnRButtonClick method

See also

Executes when users click the right mouse button on a visual object.

Syntax

Function OnRButtonClick( view As AcReportView, Shift As AcShiftKeyState,
x As Integer, y As Integer ) As Boolean

view

The window the report is in.

Shift

A bit field that indicates if the Shift, Ctrl, or Alt keys were pressed at the time of the event. See OnLButtonClick for the codes.

x

The horizontal position of the mouse cursor at the time of the event, measured in pixels relative to the left of the view.

y

The vertical position of the mouse cursor at the time of the event, measured in pixels relative to the top of the view.

Description

By default, OnRButtonClick( ) does nothing. It returns False if the event is not handled.

In derived classes, you can override OnRButtonClick( ) to perform a task when users press and release the right mouse button on a single object. If you need to execute different actions, depending on whether the right mouse button is down or up, use OnRButtonDown( ) or OnRButtonUp( ) instead.

Using the Shift values, you can assign different actions to the different key and right mouse click combinations. You can also use the x- and y-coordinates to execute different actions, depending on where the right mouse click event occurred.

In many Windows applications, the right mouse button is used for displaying context menus. By default, Actuate displays context menus when the right mouse down (OnRButtonDown) event occurs.

Return value

True if the event is handled by the current object.

False if the event is not handled.


See also

AcVisualComponent::OnRButtonDblClk method

AcVisualComponent::OnRButtonDown method

AcVisualComponent::OnRButtonUp method


AcVisualComponent::OnRButtonDblClk method

See also

Executes when users double click the right mouse button on a visual object.

Syntax

Function OnRButtonDblClk( view As AcReportView, Shift As AcShiftKeyState, x As Integer, y As Integer ) As Boolean

view

The window the report is in.

Shift

A bit field that indicates if the Shift, Ctrl, or Alt keys were pressed at the time of the event. See OnLButtonClick for the codes.

x

The horizontal position of the mouse cursor at the time of the event, measured in pixels relative to the left of the view.

y

The vertical position of the mouse cursor at the time of the event, measured in pixels relative to the top of the view.

Description

By default, OnRButtonDblClk( ) does nothing. It returns False if the event is not handled.

In derived classes, you can override OnRButtonDblClk( ) to perform a task when users double click with the right mouse button. Using the Shift values, you can assign different actions to the different key and right mouse double-click combinations. You can also use the x- and y-coordinates to execute different actions, depending on where the right mouse double-click event occurred.

In many Windows applications, the right mouse button is used for displaying context menus. By default, Actuate displays context menus when the right mouse down (OnRButtonDown) event occurs.

Return value

True if the event is handled by the current object.

False if the event is not handled.


See also

AcVisualComponent::OnRButtonClick method

AcVisualComponent::OnRButtonDown method

AcVisualComponent::OnRButtonUp method


AcVisualComponent::OnRButtonDown method

See also

Executes when the user presses the right mouse button.

Syntax

Function OnRButtonDown( view As AcReportView, Shift As AcShiftKeyState, x As Integer, y As Integer ) As Boolean

view

The window the report is in.

Shift

A bit field that indicates if the Shift, Ctrl, or Alt keys were pressed at the time of the event. See OnLButtonClick for the codes.

x

The horizontal position of the mouse cursor at the time of the event, measured in pixels relative to the left of the view.

y

The vertical position of the mouse cursor at the time of the event, measured in pixels relative to the top of the view.

Description

By default, OnRButtonDown( ) calls OnContextMenu( ), which displays the context menu at the location where the mouse event occurred. You customize the context menu by overriding AddMenuCommands( ).

In derived classes, you can override OnRButtonDown( ) to perform a different task, or to add functionality. Using the Shift values, you can assign different actions to the different key and right mouse down combinations. You can also use the x,y coordinates to execute different actions, depending on where the right mouse down event occurred.

In many Windows applications, however, the right mouse button is used solely for context menus.

Return value

True if the event is handled by the current object.

False if the event is not handled.


See also

AcVisualComponent::OnRButtonClick method

AcVisualComponent::OnRButtonDblClk method

AcVisualComponent::OnRButtonUp method


AcVisualComponent::OnRButtonUp method

See also

Executes when the user releases the right mouse button.

Syntax

Function OnRButtonUp( view As AcReportView, Shift As AcShiftKeyState,
x As Integer, y As Integer ) As Boolean

view

The window the report is in.

Shift

A bit field that indicates if the Shift, Ctrl, or Alt keys were pressed at the time of the event. See OnLButtonClick for the codes.

x

The horizontal position of the mouse cursor at the time of the event, measured in pixels relative to the left of the view.

y

The vertical position of the mouse cursor at the time of the event, measured in pixels relative to the top of the view.

Description

By default, OnRButtonUp( ) does nothing. It returns False if the event is not handled.

In derived classes, you can override OnRButtonUp( ) to perform a task when users release the right mouse button. If you need to execute an action when the right mouse button is down, use OnRButtonDown( ).

Using the Shift values, you can assign different actions to the different key and left mouse up combinations. You can also use the x- and y-coordinates to execute different actions, depending on where the right mouse up event occurred.

Return value

True if the event is handled by the current object.

False if the event is not handled.


See also

AcVisualComponent::OnRButtonClick method

AcVisualComponent::OnRButtonDblClk method

AcVisualComponent::OnLButtonDown method


AcVisualComponent::ResizeBy method

See also

Resizes a component by the distances given.

Syntax

Sub ResizeBy( deltaWidth As Integer, deltaHeight As Integer )

deltaWidth

The amount in twips by which to resize the width of the component.

deltaHeight

The amount in twips by which to resize the height of the component.

Description

The ResizeBy( ) method resizes a component by the distances given. Negative amounts make the component smaller; positive amounts make it larger.


See also

AcVisualComponent::ResizeTo method


AcVisualComponent::ResizeTo method

See also

Resizes a frame or control to the given size.

Syntax

Sub ResizeTo( newWidth As Integer, newHeight As Integer )

newWidth

The new width of the component in twips.

newHeight

The new height of the component in twips.

Description

The ResizeTo( ) method resizes a frame or control to the given size.


See also

AcVisualComponent::ResizeBy method


AcVisualComponent::Searchable method

See also

Implements the Searchable property that appears on the Properties page of the Component Editor.

Syntax

Function Searchable( ) As Boolean

Description

Searchable( ) specifies if users can search for a particular component in the Viewer. For example, users running a lengthy Customers report will probably want to search by customer names for quick access. If the customer name is stored in a text control, you should make that text control searchable.


See also

AcVisualComponent::SearchAlias method


AcVisualComponent::SearchAlias method

See also

Implements the SearchAlias property that appears on the Properties page of the Component Editor.

Syntax

Function SearchAlias( ) As String

Description

SearchAlias( ) specifies the name to display in the Search dialog box when users create a search criteria for a particular control.

Default

The object's class name.


See also

AcVisualComponent::Searchable method


AcVisualComponent::Selectable method

See also

Implements the Selectable property that appears on the Properties page of the Component Editor.

Syntax

Function Selectable( ) As Boolean

Description

Selectable specifies if users can select the visual object in the Viewer.

Return value

True if the object is selectable.

False if the object is not selectable.


See also

AcVisualComponent::Searchable method


AcVisualComponent::ShowInHTML method

Example

Determines whether or not a control is visible in the HTML report.

Syntax

Function ShowInHTML( ) As Boolean

Description

Determines whether or not the current control is visible in an HTML report. Override ShowIn HTML to prevent a control from appearing when generating HTML.  The default behavior is to return True, so that controls appear in the HTML output.


Example

The following example shows how to override ShowInHTML( ) to hide the current control in HTML output. The control appears in printed reports and in the Viewer.

Function ShowInHTML( ) As Boolean

    ShowInHTML = False

End Function

Return value

True if the control is visible.

False if the control is not visible.


AcVisualComponent::ShowWhenPrinting method

Example

Determines whether or not a control is visible in a printed report.

Syntax

Function ShowWhenPrinting( ) As Boolean

Description

Determines whether or not the current control is visible when a report is printed. Override ShowWhenPrinting to prevent a control from appearing when printing.  The default behavior is to return True, so that controls appear in the printed output.


Example

The following example shows how to override ShowWhenPrinting( ) to hide the current control when printing a report. The control appears in HTML output and in the Viewer.

Function ShowWhenPrinting( ) As Boolean

    ShowWhenPrinting = False

End Function

Return value

True if the control is visible.

False if the control is not visible.


AcVisualComponent::ShowWhenViewing method

Example

Determines whether or not a control is visible when viewing a report.

Syntax

Function ShowWhenViewing( ) As Boolean

Description

Determines whether or not the current control is visible when viewing a report. Override ShowWhenViewing to prevent a control from appearing when viewing.  The default behavior is to return True, so that controls appear in the Viewer.


Example

The following example shows how to override ShowWhenViewing( ) to hide the current control when viewing a report. The control appears in HTML output and in the printed output.

Function ShowWhenViewing( ) As Boolean

    ShowWhenViewing = False

End Function

Return value

True if the control is visible.

False if the control is not visible.


AcVisualComponent::StatusText method

Returns the value of GetLinkTo( ) if there is a hyperlink, or the help text associated with this component, otherwise.

Syntax

Function StatusText( ) as String

Description

StatusText( ) returns the value of the current component's hyperlink, if any, or the help text associated with the component. This is useful for users viewing .ROI's; you can display the link for a particular control when the cursor is placed on the control in the viewer, or display help text for the control.

Return value

The value of the hypertext link if there is one, help text if there is any, or the empty string if there is no hyperlink or help text.