ActiveXPowUpload 1.2.0.5
Events
  Home page
Contact support

ActiveXPowUpload supports its own events and builtin DHTML events.

1. You can find a lot of DHTML events at a MSDN website http://msdn2.microsoft.com/en-us/library/ms533051(VS.85).aspx

For example for the "onkeydown()" DHTML event use the following sample code:

<script for="ActiveXPowUpload" event="onkeydown()" language="JavaScript">
    //Code here
</script>

In the code inside you can call JavaScript event object methods and properties to get more information about the occurred event.

2. To use own ActiveXPowUpload events add the following sample code to the page:

<script for="ActiveXPowUpload" event="OnError(Error)" language="JavaScript">
    window.alert(Error);
</script>

All own ActiveXPowUpload events are listed below.

See also Upload events diagram, Download events diagram.

Some important builtin DHTML events:

onactivate event

Own events:

Upload events

OnAddFiles event

OnUploadPreUpdateItem event

OnDropItems event

OnUploadPreRemoveItem event

OnUploadPreRemoveAllItems event

OnRemoveFiles event

OnUploadSelectionChanged event

OnUploadFocusChanged event

OnUploadClicked event

OnUploadBegin event

OnUploadFileBegin event

OnUploadProgress event

OnUploadFileCompleted event

OnUploadFinishedBeforeReply event

OnUploadCompletedSuccessfully event

OnUploadCompletedError event

OnUploadCancelled event

OnSort event

Download events

OnDownloadBegin event

OnDownloadEnd event

OnDownloadFileBegin event

OnDownloadFileSuccess event

OnDownloadFileError event

OnDownloadProgress event

OnDownloadCancelled event

OnDownloadFolderChanged event

OnDownloadAddFiles event

OnDownloadRemoveFiles event

OnDownloadSelectionChanged event

OnDownloadFocusChanged event

OnDownloadSort event

Other events

OnServerError event

OnError event

OnMessage event

OnLog event

onactivate

event onactivate() {}

Builtin DHTML event. Fires when the object is set as the active element. This event helpfull if you want to call ActiveXPowUpload properties or methods right away after it will loaded. It is impossible to call any ActiveXPowUpload code before user will make "Click to activate" or workaround will be loaded. This event fires after control loaded and "Click to activate" done.

Example

<script for="ActiveXPowUpload" event="onactivate()" language="JavaScript">
    //Any initialization code here
</script>

OnAddFiles

event OnAddFiles(NumberOfItems:Long, NumberOfFiles:Long, TotalSize:Long) {}

Invoked after new files or folders added to list. ActiveXPowUpload doesn't add files that are already in the list. If file is already in the list, all information related to it updated. File saves its position in the file list i.e. index left unchanged.

New files are added to the end of the list so you can enumerate new files by index: from ActiveXPowUpload.FileListItemCount-1 down to ActiveXPowUpload.FileListItemCount-NumberOfItems-1.

Parameters

NumberOfItems:Long

Number of items added, files and folders.

NumberOfFiles:Long

Number of files added.

TotalSize:Long

Total size of added files.

Example

<script for="ActiveXPowUpload" event="OnAddFiles(NumberOfItems, NumberOfFiles, TotalSize)" language="JavaScript">
    window.alert("added files count " + NumberOfFiles + ", total size=" + TotalSize);
</script>

OnUploadPreUpdateItem

event OnUploadPreUpdateItem(UpdateItemIndex:Long, NewItem:Variant) {}

Invoked just be before the item having index UpdateItemIndex in the upload file list is updated.

The upload file list may contain only one item corresponding to one file or folder. The list may not contain duplicates. When an item that is already contained in the list is added again, new item is not inserted, instead the existed item is updated. That makes sense since some properties of the file may have changed. The file may be modified, for example.

The event is invoked before the actual update, so the upload file list contains old data. The being updated item may be accessed in the normal way. The NewItem parameter referes to a FileItem object, describing new file state.

Parameters

UpdateItemIndex:Long

Index of the item that is updated.

NewItem:Variant

A reference to a FileItem object, describing new file state.

Example

<script for="ActiveXPowUpload" event="OnUploadPreUpdateItem(UpdateItemIndex, NewItem)" language="JavaScript">
	var OldObject = ActiveXPowUpload.UploadItems(UpdateItemIndex);
	var NewObject = NewItem;
</script>

OnDropItems

event OnDropItems(NumberOfItems:Long) {}

Invoked after files were dropped (drag-n-drop) on the component. NumberOfItems is not the same as number of files! If user copies one folder to clipborad, NumberOfItems will be 1, regardless of the number of files in that folder.

Parameters

NumberOfItems:Long

Number of items dropped.

Example

<script for="ActiveXPowUpload" event="OnDropItems(NumberOfItems)" language="JavaScript">
    window.alert("Dropped items count " + NumberOfItems);
</script>

OnUploadPreRemoveItem

event OnUploadPreRemoveItem(ItemNumber:Long) {}

Invoked just before the item having index ItemNumber is removed from the upload list.

Parameters

ItemNumber:Long

Index of the item to be removed.

See also OnUploadPreRemoveAllItems event.

Example

<script for="ActiveXPowUpload" event="OnUploadPreRemoveItem(ItemNumber)" language="JavaScript">
window.alert("About to remove item " + ItemNumber);
</script>

OnUploadPreRemoveAllItems

event OnUploadPreRemoveAllItems() {}

Invoked just before all items are removed from the upload list.

This event corresponds to the case when the upload file list is cleared. This can be done though GUI, or invoking the RemoveAllFiles method. This event is not invoked when upload items are deleted one by one. For that case see OnUploadPreRemoveItem event. For every operation that removes files from the upload file list either this or OnUploadPreRemoveItem (never both) event is fired.

Example

<script for="ActiveXPowUpload" event="OnUploadPreRemoveAllItems()" language="JavaScript">
    window.alert("About to remove all items");
</script>

OnRemoveFiles

event OnRemoveFiles(NumberOfItems:Long, NumberOfFiles:Long, TotalSize:Long) {}

Invoked after items removed from the list.

Parameters

NumberOfItems:Long

Number of items removed, files and folders.

NumberOfFiles:Long

Number of files removed.

TotalSize:Long

Total size of the removed files.

Example

<script for="ActiveXPowUpload" event="OnRemoveFiles(NumberOfItems, NumberOfFiles, TotalSize)" language="JavaScript">
    window.alert("Removed files count " + NumberOfFiles + ", total size=" + TotalSize);
</script>

OnUploadSelectionChanged

event OnUploadSelectionChanged(ItemNumber:Long, Selected:bool) {}

Invoked when user changed selection in the upload file list.

Description

Each upload list item can be other selected or not. Selected items usually have different background color. User can change selection using keyboard and mouse. This even occures when selection changes. Each item being changed its state fires independ OnUploadSelectionChanged event. The first parameter is the item number in the upload file list. The second parameter is the new item state. If Selected = true, the item was selected, if Selected = false, the item was unselected.

See also Selected property.

Parameters

ItemNumber:Long

Item number in the upload file list.

Selected:bool

New item state, whether it is selected or not.

OnUploadFocusChanged

event OnUploadFocusChanged(ItemNumber:Long, Focus:bool) {}

Invoked when upload file list focus changes.

Description

The item that has the focus in the upload file list is surrounded by a standard focus rectangle. Although more than one item may be selected, only one item can have the focus. When you click on an item in the list that item becomes selected and gets the focus.

Parameters

ItemNumber:Long

Item number in the upload file list.

Focus:bool

New item state, whether it has the focus or not.

OnUploadClicked Obsolete

event OnUploadClicked() {}

Invoked immediately after an Upload popup menu item is clicked or the Upload method is called.

This event was added to perform last-minutes tweaks before upload. Now it is possible to tweak ActiveXPowUpload in the OnUploadBegin event. Use it instead. The OnUploadClicked event is left for compatibility reasons.

See also Upload events diagram.

OnUploadBegin

event OnUploadBegin() {}

Invoked just after the upload process has been started. Upload ends with either OnUploadCompletedSuccessfully or OnUploadCompletedError event.

You may perform last-minute tweaks in that event. For example, you may remove some files from the upload file list, add/remove items text items to upload (see the FormItem property), etc. See the example bellow.

You may cancel upload invoking the Stop method. In that case ActiveXPowUpload does not connect to the server and terminates the upload action just after firing the following events: OnUploadCancelled, OnUploadCompletedError, OnError. In fact, that sequence of events is fired whenever upload is cancelled no matter when it happens during the real upload, before the real upload.

See also OnUploadCompletedSuccessfully, OnUploadCompletedError.

Example

<script for="ActiveXPowUpload" event="OnUploadBegin()" language="JavaScript">
	// remove files with zero size 
	for(var i = 0; i<ActiveXPowUpload.FileListItemCount; ++i)
		if(ActiveXPowUpload.GetItem(i).Size == 0) {
			ActiveXPowUpload.RemoveFile(i);
			--i;
		}
</script>

OnUploadFileBegin

event OnUploadFileBegin(FileName:String) {}

Invoked when individual file body starts to upload. All files in the list are sent in a single POST request. While a part of the request containing individual file body uploads this event occures. You can use this event to let a user know which files was already uploded and the file that is uploaded right now. Some of server side scripts can save files that was uploaded even if a whole request not uploaded (See our product PowUpload ASP.NET server control).

Parameters

FileName:String

Full path of the file that is started to upload.

Example

<script for="ActiveXPowUpload" event="OnUploadFileBegin(FileName)" language="JavaScript">
    window.alert("Uploading file " + FileName);
</script>

OnUploadProgress

event OnUploadProgress(CurrentPartName:String, CurrentPartSize:Long, CurrentPartBytesUploaded:Long, TotalSize:Long, TotalBytesUploaded:Long, ElapsedTime:Long, LeftTime:Long, CurrentSpeed:Double, AverageSpeed:Double) {}

Invoked periodically during the upload process. POST request has RFC 1867 format. It consists of text Form items at the begin with some header data and then files body, each with some header data at the begin. At the end of the request there are few bytes of a closing boundary.

Parameters

CurrentPartName:String

Name of currently uploaded part of request. It can be 1. "<text fields>" if text Form items uploaded, 2. Full file path if file uploaded or 3. Empty string if final boundary uploaded.

CurrentPartSize:Long

Total size of currently uploaded part of request, in bytes. For files it is size of file + header data size.

CurrentPartBytesUploaded:Long

Already uploaded size of currently uploaded part, in bytes.

TotalSize:Long

Total size of whole request, in bytes.

TotalBytesUploaded:Long

Already uploaded size of request, in bytes.

ElapsedTime:Long

How many time has elapsed since the upload starts, in milliseconds. Divide this value by 1000 to get seconds.

LeftTime:Long

How many time left to finish upload based on the average speed, in milliseconds.

CurrentSpeed:Double

Current speed of the upload, in bytes per second.

AverageSpeed:Double

Average speed of the upload, in bytes per second.

Example

<script for="ActiveXPowUpload" event="OnUploadProgress(CurrentPartName, CurrentPartSize, CurrentPartBytesUploaded, TotalSize, TotalBytesUploaded, ElapsedTime, LeftTime, CurrentSpeed, AverageSpeed)" language="JavaScript">
    //Code here
</script>

OnUploadFileCompleted

event OnUploadFileCompleted(FileName:String) {}

Invoked after individual file has been completely uploaded. All files at list sends in single POST request. After a part of the request containing individual file body is uploaded this event occures.

Parameters

FileName:String

Full path of file that was uploaded.

Example

<script for="ActiveXPowUpload" event="OnUploadFileCompleted(FileName)" language="JavaScript">
    window.alert("Uploaded file " + FileName);
</script>

OnUploadFinishedBeforeReply

event OnUploadFinishedBeforeReply() {}

This event occurs immediately after all data have been uploaded. We don't get server reply yet.

Example

<script for="ActiveXPowUpload" event="OnUploadFinishedBeforeReply()" language="JavaScript">
    window.alert("Upload finished, please wait for server reply!");
</script>

OnUploadCompletedSuccessfully

event OnUploadCompletedSuccessfully() {}

Invoked after upload has successfully completed.

See also OnUploadCompletedError.

Example

<script for="ActiveXPowUpload" event="OnUploadCompletedSuccessfully()" language="JavaScript">
	window.alert("Upload finished successfully! Server reply: " + ActiveXPowUpload.GetServerReply(65001));
</script> 

OnUploadCompletedError

event OnUploadCompletedError(Error: String) {}

Invoked after upload has failed. The Error parameter contains error description.

Parameters

Error: String

Error description.

See also OnUploadCompletedSuccessfully.

OnUploadCancelled

event OnUploadCancelled() {}

Invoked when the upload process discovers the cancel request. Upload stops, a connection with the server is closed. The OnUploadCancelled event is followed by the OnUploadCompletedError, and OnError events.

Example

<script for="ActiveXPowUpload" event="OnUploadCancelled()" language="JavaScript">
    window.alert("Upload cancelled!");
</script>

OnDownloadBegin

event OnDownloadBegin() {}

Invoked when the download process starts. By that time the component has checked that the download folder exists. The Name property of all download files contain a normalized file name.

OnDownloadEnd

event OnDownloadEnd() {}

Invoked when the download process completed. All files are downloaded or failed to download. If download is started (i.e. the OnDownloadBegin event is fired), the OnDownloadEnd event will be fired anyway, even if an error occured.

OnDownloadFileBegin

event OnDownloadFileBegin(Index: long) {}

Invoked immediately before the file with the index "Index" is downloaded. File state is "Download in progress".

Parameters

Index: long

An index of the download file. See the GetDownloadItem method.

OnDownloadFileSuccess

event OnDownloadFileSuccess(Index: long) {}

Invoked immediately after the file with the index "Index" is successfully downloaded. File state is "Download completed successfully".

Parameters

Index: long

An index of the download file. See the GetDownloadItem method.

OnDownloadFileError

event OnDownloadFileError(Index: long) {}

File with the index "Index" failed to download. File state is "Error".

Parameters

Index: long

An index of the download file. See the GetDownloadItem method.

OnDownloadProgress

event OnDownloadProgress( CurFileIndex: long, CurFileSize: long, CurFileBytesDownloaded: long, TotalSize: long, TotalBytesDownloaded: long, ElapsedTime: long, LeftTime: long, CurSpeed: double, AvgSpeed: double) {}

Invoked periodically during the download process. Statistics is countered for the list of being downloaded file.

Parameters

CurFileIndex: long

An index of the currently being downloaded file. Use the GetDownloadItem method to get more information about the current file.

CurFileSize: long

Size of the currently being downloaded file in bytes. It is not always possible to determine the file size. In the case the file size is undefined, it would be equal to the number of bytes downloaded til this moment. So CurFileSize would be equal to CurFileBytesDownloaded.

CurFileBytesDownloaded: long

Number of bytes of the current file downloaded til this moment.

TotalSize: long

Total size of the files in the download list. Note that sizes of the files that are not downloaded are not known unless the size was specified explicitly when the file was added.

TotalBytesDownloaded: long

Number of bytes were downloaded til this moment.

ElapsedTime: long

How many time has elapsed since the download starts, in seconds.

LeftTime: long

How many time left to finish download based on the average speed, in seconds.

CurSpeed: long

Current speed of the download, in bytes per second.

AvgSpeed: long

Average speed of the download, in bytes per second.

Example

<script for="ActiveXPowUpload" event="OnDownloadProgress(CurrentFileIndex,  CurrentFileSize, CurrentFileBytesDownloaded, TotalSize, TotalBytesDownloaded, ElapsedTime, LeftTime, CurrentSpeed,  AverageSpeed)" language="JavaScript">
//Code here 
</script>

OnDownloadCancelled

event OnDownloadCancelled() {}

Invoked when the download process was cancelled.

OnServerError

event OnServerError() {}

Invoked if server returned HTTP error while starting or finishing request. Use GetServerReply, GetServerStatusCode and GetServerStatusText methods to get reply content.

Example

<script for="ActiveXPowUpload" event="OnServerError()" language="JavaScript">
    window.alert("Error occured: " + ActiveXPowUpload.GetServerReply(65001));
</script>

OnError

event OnError(Error:String) {}

Invoked if some an error occured.

Parameters

Error:String

The description of error.

Example

<script for="ActiveXPowUpload" event="OnError(Error)" language="JavaScript">
    window.alert("Error occured: " + Error);
</script>

OnMessage

event OnMessage(Message:String) {}

Fired when an event happened the user should know about. E.g. some files have been skipped when a group of files were added to the file list.

Parameters

Message:String

Message description.

Example

<script for="ActiveXPowUpload" event="OnMessage(Message)" language="JavaScript">
    window.alert("Message received: " + Message);
</script>

OnSort

event OnSort(column:Long, order:Long) {}

Fired after the upload file list has been sorted. It usually happens when the user clicks on the file list header.

Parameters

column:Long

column number. 0 - file name column, 1 - file size column.

order:Long

sort order code. 0 - ascending, 1 - descending.

Example

<script language="jscript">
function getUploadColumnNameByNumber(num) {
	switch(num)
	{
	case 0: return "FileName";
	case 1: return "Size";
	default: return "None";
	}
}
function getColumnSortOrderNameByNumber(ord) {
	switch(ord)
	{
	case 0: return "Asc";
	case 1: return "Des";
	default: return "None";
	}
}
</script>
<script for="ActiveXPowUpload" event="OnSort(col,ord)" language="JavaScript">
	window.alert("Upload file list has been sorted on " + getUploadColumnNameByNumber(col) 
		+ " column, in " + getColumnSortOrderNameByNumber(ord) + " order.");
</script>

OnLog

event OnLog(message:String) {}

Gets debug messages.

Parameters

Message:String

debug message.

See also debug.

Example

<script for="ActiveXPowUpload" event="OnLog(msg)" language="JavaScript">
    events.value = events.value + "OnLog(" + msg + ")\n"
</script>
<TEXTAREA NAME="events" ROWS=10 COLS=100>
</TEXTAREA>

OnDownloadFolderChanged

event OnDownloadFolderChanged() {}

Fired when the DownloadFolder property changes.

OnDownloadAddFiles

event OnDownloadAddFiles(NumberOfItems:Long, TotalSize:Long) {}

Invoked after new items added to the download list. ActiveXPowUpload doesn't add items that are already in the list. If file is already in the list, all information related to it is updated. File saves its position in the file list i.e. index left unchanged.

New files are added to the end of the list so you can enumerate new files by index: from ActiveXPowUpload.DownloadFileCount-1 down to ActiveXPowUpload.DownloadFileCount-NumberOfItems-1.

Parameters

NumberOfItems:Long

Number of items added, files and folders.

TotalSize:Long

Total size of added files (files with unknown sizes are not counted).

OnDownloadRemoveFiles

event OnDownloadRemoveFiles(NumberOfItems:Long, TotalSize:Long) {}

Invoked after items removed from the download list.

Parameters

NumberOfItems:Long

Number of items removed.

TotalSize:Long

Total size of the removed files (files with unknown sizes are not counted).

OnDownloadSelectionChanged

event OnDownloadSelectionChanged(ItemNumber:Long, Selected:bool) {}

Invoked when user changed selection in the download file list.

Description

Each download list item can be other selected or not. Selected items usually have different background color. User can change selection using keyboard and mouse. This event occures when selection changes. Each item being changed its state fires independ OnDownloadSelectionChanged event. The first parameter is the item number in the download file list. The second parameter is the new item state. If Selected = true, the item is selected, if Selected = false, the item is not selected.

See also Selected property.

Parameters

ItemNumber:Long

Item number in the download file list.

Selected:bool

New item state, whether it is selected or not.

OnDownloadFocusChanged

event OnDownloadFocusChanged(ItemNumber:Long, Focus:bool) {}

Invoked when download file list focus changes.

Description

The item that has the focus in the download file list is surrounded by a standard focus rectangle. Although more than one item may be selected, only one item can have the focus. When you click on an item in the list that item becomes selected and gets the focus.

Parameters

ItemNumber:Long

Item number in the download file list.

Focus:bool

New item state, whether it has the focus or not.

OnDownloadSort

event OnDownloadSort(column:Long, order:Long) {}

Fired after the download file list has been sorted. It usually happens when the user clicks on the file list header.

Parameters

column:Long

column number. 0 - file name column, 1 - file size column, 2 - URL column.

order:Long

sort order code. 0 - ascending, 1 - descending.

Example

<script language="jscript">
function getDownloadColumnNameByNumber(num) {
	switch(num)
	{
	case 0: return "FileName";
	case 1: return "Size";
	case 2: return "URL";
	default: return "None";
	}
}
function getColumnSortOrderNameByNumber(ord) {
	switch(ord)
	{
	case 0: return "Asc";
	case 1: return "Des";
	default: return "None";
	}
}
</script>
<script for="ActiveXPowUpload" event="OnDownloadSort(col,ord)" language="JavaScript">
	window.alert("Download file list has been sorted on " + getDownloadColumnNameByNumber(col) 
		+ " column, in " + getColumnSortOrderNameByNumber(ord) + " order.");
</script>