IMPORTANT NOTICE - Apr-30-2009:
This .NET implementation of Okapi is no longer actively developed.
Instead, a NEW JAVA IMPLEMENTATION IS AVAILABLE and is being actively developed.

The material on this Web site is for archive propose. Some applications of the old .NET implementation (e.g. Olifant) will be maintained to some degree until they have a replacement in the Java project.

Okapi Framework

Log Interface Specification

Revision information: Version 1.1
     Latest revision: http://okapi.sourceforge.net/ILog.html

- Document Status
- Overview
- Defined Values
- Methods

Document Status

This document is a stable specification. Feedback about the content of this document is encouraged. Send your comments to the Okapi Framework administrator, or alternatively to post them in the Okapi Tools users group.

DISCLAIMER: Parts of the documents are generated automatically from the source code documentation of Okapi's implementation of the specification. Because the generation tool is not completely working yet, this may result in incomplete or broken text or links in this document. See the source code documentation of the interface for complete text.

Overview

The Okapi Log Interface is an object model that provides a common way of accessing a common log mechanism for the different Okapi components. It is used by nearly all components, high-level as well as low-level.

Other related specifications:

Defined Values

The following defined values are used with the ILog interface:

Log Type

The log types are used with the SetLog method to specify what type of information should be displayed or processed. The types currently defined are the following:

0 (MAINPROGRESS)

Constant value = 0. Changes the main progress indicator.

1 (SUBPROGRESS)

Constant value = 1. Changes the secondary progress indicator.

2 (MESSAGE)

Constant value = 2. Displays a specified message.

3 (WARNING)

Constant value = 3. Displays a specified warning message.

4 (ERROR)

Constant value = 4. Displays a specified error message.

5 (USERFEEDBACK)

Constant value = 5. Checks if the user has cancelled the process.

Methods

The Log Interface provides the following methods:

ILog.SetCallerData

Sets the implementation-specific data of the caller.

ILog.GetCallerData

Gets the implementation-specific data of the caller set by ILog.SetCallerData.

ILog.SetHelp

Sets the help access information for the log.

ILog.InProgress

Indicates whether a task is in progress.

ILog.IsVisible

Indicates whether the log user interface is visible.

ILog.Show

Shows the log user interface.

ILog.Hide

Hides the log user interface.

ILog.SetOnTop

Switches the log user interface to be pinned on top of the screen or not.

ILog.SetMainProgressMode

Sets the mode of the main progress indicator.

ILog.SetSubProgressMode

Sets the mode of the secondary progress indicator.

ILog.SetTitle

Sets the title/caption of the log.

ILog.Clear

Clears the log.

ILog.Cancel

Cancel the current task/process.

ILog.GetErrorCount

Gets the number of errors since the last call to the ILog.BeginProcess method.

ILog.GetWarningCount

Gets the number of warnings since the last call to the ILog.BeginProcess method.

ILog.GetErrorAndWarningCount

Gets the number of errors and warnings since the last call to the ILog.BeginProcess method.

ILog.SetLog

Log an entry in the log or query the user's feedback.

ILog.Message

Logs a message.

ILog.Warning

Logs a warning message.

ILog.Error

Logs an error message.

ILog.Continue

Queries if the user has cancelled the process.

ILog.NewLine

Logs an empty line.

ILog.BeginProcess

Starts a process.

ILog.EndProcess

Ends the current process.

ILog.BeginTask

Starts a task within a process.

ILog.EndTask

Ends the current task.

ILog.Save

Saves the current content of the log to a file.

ILog.SetCallerData

Sets the implementation-specific data of the caller.

ILog.GetCallerData

Gets the implementation-specific data of the caller set by ILog.SetCallerData.

Return

The caller data value.

ILog.SetHelp

Sets the help access information for the log.

Parameters

Stringp_sValueHelp access information.

Remarks

Use this method to associate an help with a possible Help button in the user interface of the log. Note that not all implementation of the interface have an Help button.

The actual value of the p_sValue parameter depends on the implementation of the log. Usually it will be the full path to an help file.

ILog.InProgress

Indicates whether a task is in progress.

Return

True if a task is already in progress, false if not.

ILog.IsVisible

Indicates whether the log user interface is visible.

Return

True if the log is visible, false if not.

ILog.Show

Shows the log user interface.

Remarks

Use this method to show the log user interface. Note that some implementations of the Base.ILog interface may not provide a way to show the user interface. For example an output to a log file.

ILog.Hide

Hides the log user interface.

Remarks

Use this method to hide the log user interface. Note that some implementations of the Base.ILog interface may not provide a way to hide the user interface. For example the log of a console output.

ILog.SetOnTop

Switches the log user interface to be pinned on top of the screen or not.

Parameters

System.Booleanp_bValueTrue if the user interface should be on top, false otherwise.

Return

True if the log was already set on top, false if it was not.

Remarks

Use this method to pin or unpin the log user interface on top of the other windows.

This method may have no effect with some implementations of the log where being windows are not used (like with a console or a file output).

ILog.SetMainProgressMode

Sets the mode of the main progress indicator.

Parameters

Integerp_nValueThe new mode to set.

Remarks

The value is one of the Base.LogProgressMode values.

ILog.SetSubProgressMode

Sets the mode of the secondary progress indicator.

Parameters

Integerp_nValueThe new mode to set.

Remarks

The value is one of the Base.LogProgressMode values.

ILog.SetTitle

Sets the title/caption of the log.

Parameters

Stringp_sValueThe text to use as title/caption for the log.

ILog.Clear

Clears the log.

ILog.Cancel

Cancel the current task/process.

Parameters

System.Booleanp_bAskConfirmationIndicator wether a confirmation prompt should be issue before cancelling.

ILog.GetErrorCount

Gets the number of errors since the last call to the ILog.BeginProcess method.

Return

The number of errors since the last call to the ILog.BeginProcess method.

ILog.GetWarningCount

Gets the number of warnings since the last call to the ILog.BeginProcess method.

Return

The number of warnings since the last call to the ILog.BeginProcess method.

ILog.GetErrorAndWarningCount

Gets the number of errors and warnings since the last call to the ILog.BeginProcess method.

Return

The number of errors and warnings since the last call to the ILog.BeginProcess method.

ILog.SetLog

Log an entry in the log or query the user's feedback.

Parameters

Integerp_nTypeType of action to perform. The value must be one of the Base.LogType values.
Integerp_nValueNumeric parameter. The value depends on the type of action to perform.
Stringp_sValueString parameter. The value depends on the type of action to perform.

Return

True if the process is to be continued, false if the user has cancelled the process.

ILog.Message

Logs a message.

Parameters

Stringp_sTextText of the message.

Return

True if the process is to be continued, false if the user has cancelled the process.

Remarks

Calling this method is the same as calling Log(2, 0, p_sText).

ILog.Warning

Logs a warning message.

Parameters

Stringp_sTextText of the warning message.

Return

True if the process is to be continued, false if the user has cancelled the process.

Remarks

Calling this method is the same as calling Log(3, 0, p_sText).

ILog.Error

Logs an error message.

Parameters

Stringp_sTextText of the error message.

Return

True if the process is to be continued, false if the user has cancelled the process.

Remarks

Calling this method is the same as calling Log(4, 0, p_sText).

ILog.Continue

Queries if the user has cancelled the process.

Return

True if the process is to be continued, false if the user has cancelled the process.

Remarks

Calling this method is the same as calling Log(5, 0, null).

ILog.NewLine

Logs an empty line.

Return

True if the process is to be continued, false if the user has cancelled the process.

Remarks

Calling this method is the same as calling Log(2, 0, "").

ILog.BeginProcess

Starts a process.

Parameters

Stringp_sTextOptional text to display. Set the text to null or empty to display nothing.

Return

True if the process could be started, false otherwise.

ILog.EndProcess

Ends the current process.

Parameters

Stringp_sTextOptional text to display. Set the text to null or empty to display nothing.

ILog.BeginTask

Starts a task within a process.

Parameters

Stringp_sTextOptional text to display. Set the text to null or empty to display nothing.

Return

True if the task could be started, false otherwise.

ILog.EndTask

Ends the current task.

Parameters

Stringp_sTextOptional text to display. Set the text to null or empty to display nothing.

ILog.Save

Saves the current content of the log to a file.

Parameters

Stringp_sPathFull path of the file to save.