();
+ for (int i = 0; i < browserList.size(); i++) {
+ IConfigurationElement element = (IConfigurationElement) browserList.get(i);
+ if (!element.getContributor().getName().equals(Activator.PLUGIN_ID)) {
+ browserNames.add(BrowserExtensionLoader.getBrowserLabel((IConfigurationElement)
+ browserList.get(i)));
+ }
+ }
+
+ String[][] options = new String[browserNames.size()][2];
+ for (int i = 0; i < options.length; i++) {
+ options[i][0] = (String) browserNames.get(i);
+ options[i][1] = (String) browserNames.get(i);
+ }
+
+ addField(new RadioGroupFieldEditor(WIDGET_BROWSER_PREVIEW_PREFERENCE,
+ "Browser Options", 1, options, getFieldEditorParent(), true));
+*/
+ }
+
+ /* (non-Javadoc)
+ * @see org.eclipse.ui.IWorkbenchPreferencePage#init(org.eclipse.ui.IWorkbench)
+ */
+ public void init(IWorkbench workbench) {
+ }
+}
diff -r ec3f1313ae92 -r 641b65b14318 org.symbian.tools.wrttools.previewer/src/org/symbian/tools/wrttools/previewer/utils/Check.java
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.previewer/src/org/symbian/tools/wrttools/previewer/utils/Check.java Wed Jan 20 16:51:26 2010 -0800
@@ -0,0 +1,129 @@
+/**
+ * Copyright (c) 2009 Symbian Foundation and/or its subsidiary(-ies).
+ * All rights reserved.
+ * This component and the accompanying materials are made available
+ * under the terms of the License "Eclipse Public License v1.0"
+ * which accompanies this distribution, and is available
+ * at the URL "http://www.eclipse.org/legal/epl-v10.html".
+ *
+ * Initial Contributors:
+ * Symbian Foundation - initial contribution.
+ * Contributors:
+ * Description:
+ * Overview:
+ * Details:
+ * Platforms/Drives/Compatibility:
+ * Assumptions/Requirement/Pre-requisites:
+ * Failures and causes:
+ */
+package org.symbian.tools.wrttools.previewer.utils;
+
+import org.symbian.tools.wrttools.previewer.utils.noexport.Messages;
+
+import org.eclipse.core.runtime.IStatus;
+import org.eclipse.core.runtime.Platform;
+
+
+/**
+ * Utilities for runtime checking of correctness.
+ *
+ * @author eswartz
+ *
+ */
+public class Check {
+ /**
+ * Report a failure. This logs the failure and reports a dialog in debug mode.
+ *
+ * @param message human-readable message
+ * @param thr the exception to report
+ */
+ public static void reportFailure(String message, Throwable thr) {
+ try {
+ IStatus status = Logging.newSimpleStatus(1 /* our caller */,
+ IStatus.ERROR,
+ message,
+ thr);
+ Logging.log(UtilsPlugin.getDefault(), status);
+ if (Platform.isRunning() && Platform.inDebugMode())
+ Logging.showErrorDialog(Messages.getString("Check.RuntimeError"), null, status); //$NON-NLS-1$
+ } catch (Throwable e) {
+ // ignore: don't recursively fail
+ }
+ }
+
+ /**
+ * Verify an argument is not null else throw a runtime exception
+ *
+ * It's not necessary to use this unless you're storing the object
+ * away for later use -- otherwise just deference it and let the runtime
+ * throw for you!
+ *
+ * @param obj
+ * @throws NullPointerException
+ */
+ static public void checkArg(Object obj) {
+ if (obj == null) {
+ RuntimeException thr = new NullPointerException();
+ reportFailure(Messages.getString("Check.ArgumentIsNull"), thr); //$NON-NLS-1$
+ throw thr;
+ }
+ }
+
+
+ /**
+ * Verify an argument satisfies a condition else throw a runtime exception
+ *
+ * @param condition test which must return true
+ * @throws IllegalArgumentException
+ */
+ static public void checkArg(boolean condition) {
+ if (!condition) {
+ RuntimeException thr = new IllegalArgumentException();
+ reportFailure(Messages.getString("Check.ArgumentIsInvalid"), thr); //$NON-NLS-1$
+ throw thr;
+ }
+ }
+
+ /**
+ * Verify an invariant of object state holds else throw a runtime exception.
+ * This is typically used to verify an object is internally consistent.
+ *
+ * @param condition test which must return true
+ * @throws IllegalStateException
+ */
+ static public void checkState(boolean condition) {
+ if (!condition) {
+ RuntimeException thr = new IllegalStateException();
+ reportFailure(Messages.getString("Check.ObjectIsInconsistent"), thr); //$NON-NLS-1$
+ throw thr;
+ }
+ }
+
+ /**
+ * Verify an invariant related to promised behavior holds else throw a runtime exception
+ * This is typically used to ensure a client API works as expected.
+ *
+ * @param condition test which must return true
+ * @throws AssertionError
+ */
+ static public void checkContract(boolean condition) {
+ if (!condition) {
+ AssertionError thr = new AssertionError();
+ reportFailure(Messages.getString("Check.ApiAssertionFailed"), thr); //$NON-NLS-1$
+ throw thr;
+ }
+ }
+
+ /**
+ * Throw a runtime exception to indicate a test on an argument
+ * failed due to another exception.
+ *
+ * @param thr the throwable that resulted from an argument test
+ * @throws IllegalArgumentException
+ */
+ public static void failedArg(Throwable thr) {
+ IllegalArgumentException exc = new IllegalArgumentException();
+ exc.initCause(thr);
+ throw exc;
+ }
+}
diff -r ec3f1313ae92 -r 641b65b14318 org.symbian.tools.wrttools.previewer/src/org/symbian/tools/wrttools/previewer/utils/FileUtils.java
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.previewer/src/org/symbian/tools/wrttools/previewer/utils/FileUtils.java Wed Jan 20 16:51:26 2010 -0800
@@ -0,0 +1,851 @@
+/**
+ * Copyright (c) 2009 Symbian Foundation and/or its subsidiary(-ies).
+ * All rights reserved.
+ * This component and the accompanying materials are made available
+ * under the terms of the License "Eclipse Public License v1.0"
+ * which accompanies this distribution, and is available
+ * at the URL "http://www.eclipse.org/legal/epl-v10.html".
+ *
+ * Initial Contributors:
+ * Symbian Foundation - initial contribution.
+ * Contributors:
+ * Description:
+ * Overview:
+ * Details:
+ * Platforms/Drives/Compatibility:
+ * Assumptions/Requirement/Pre-requisites:
+ * Failures and causes:
+ */
+package org.symbian.tools.wrttools.previewer.utils;
+
+import org.eclipse.core.resources.*;
+import org.eclipse.core.runtime.*;
+import org.eclipse.swt.widgets.Shell;
+import org.osgi.framework.Bundle;
+
+import java.io.*;
+import java.net.*;
+import java.util.*;
+
+/**
+ * @author eswartz
+ *
+ */
+public class FileUtils {
+
+ // special IStatus code for file modified during validateEdit
+ public static final int MODIFIED_FILES_STATUS = 1000;
+
+ /** Copy files or directories from 'from' to 'to'.
+ *
+ * Recursively descends if 'from' is a directory.
+ * Creates 'from' tail directory in 'to', e.g.:
+ * from = c:/foo/bar
+ * to = c:/temp
+ *
+ * -->
+ *
+ * c:/temp/bar
+ *
+ * @param from
+ * @param to
+ * @param filter the filename filter, or null
+ */
+ public static void copyTree(File from, File to, FileFilter filter) throws IOException {
+ File[] children;
+
+ if (!from.exists()) {
+ throw new IOException ("Source of copy \'" + from.getName() + "\' doesn't exist");
+ }
+
+ if (to.getCanonicalPath().equals(from.getCanonicalPath())) {
+ throw new IOException ("\'" + from.getName() + "\' cannot copy to itself");
+ }
+
+ if (from.isDirectory()) {
+ children = from.listFiles(filter);
+ // just like cp command, if target exist, make a new folder into
+ // the target, copy content into the target folder
+ if (to.exists()) {
+ if (to.isFile()) {
+ throw new IOException("Cannot overwrite non-directory \'" + to.getName() + "\' with directory " + from.getName());
+ }
+ // copy into new directory name grafted after the existing one
+ to = new File(to, from.getName());
+ copyTree(from, to, filter);
+ return;
+ } else {
+ // copy into new directory name
+ to.mkdir();
+ for (int i = 0; i < children.length; i++) {
+ File curto = new File(to, children[i].getName());
+
+ copyTree(children[i], curto, filter);
+ }
+ return;
+ }
+ }
+ else {
+ if (to.isDirectory()) {
+ to = new File (to, from.getName());
+ }
+ copyFile(from, to);
+ return;
+ }
+
+ }
+
+ /** Copy files or directories from 'from' to 'to'.
+ *
+ * Recursively descends if 'from' is a directory.
+ * Does not create 'from' tail directory in 'to', e.g.:
+ * from = c:/foo/bar contains a,b,c
+ * to = c:/temp
+ *
+ * -->
+ *
+ * c:/temp/a
+ * c:/temp/b
+ * c:/temp/c
+ *
+ * @param from
+ * @param to
+ * @param filter the filename filter, or null
+ */
+ public static void copyTreeNoParent(File from, File to, FileFilter filter) throws IOException {
+ File[] files;
+
+ Check.checkArg(from.isDirectory());
+
+ files = from.listFiles(filter);
+ to.mkdirs();
+
+ for (int i = 0; i < files.length; i++) {
+ if (files[i].isDirectory()) {
+ //File curto = new File(to, files[i].getName());
+ //curto.mkdirs();
+ copyTree(files[i], to, filter);
+ }
+ else {
+ File curto = new File(to, files[i].getName());
+ copyFile(files[i], curto);
+ }
+ }
+
+ }
+
+ /**
+ * Copy from an input stream to a file
+ *
+ * @param in
+ * @param to
+ * @throws IOException
+ */
+ public static void copyFile(InputStream in, File to) throws IOException {
+ FileOutputStream out = new FileOutputStream(to);
+ int len;
+ byte[] buffer = new byte[4096];
+ while ((len = in.read(buffer)) != -1) {
+ out.write(buffer, 0, len);
+ }
+ out.close();
+ in.close();
+ }
+
+ /** Copy a single file from 'from' to 'to'
+ *
+ * @param from
+ * @param to
+ * @throws IOException
+ */
+ public static void copyFile(File from, File to) throws IOException {
+ FileInputStream in = new FileInputStream(from);
+ copyFile(in, to);
+ }
+
+ /** Delete a directory tree recursively.
+ *
+ * Does not delete file.
+ * @param file start point for deletion -- not itself deleted
+ */
+ public static void delTree(File file) {
+ File[] files = file.listFiles();
+ if (files != null) {
+ for (int i = 0; i < files.length; i++) {
+ if (files[i].isDirectory()) {
+ delTree(files[i]);
+ }
+ }
+ }
+ files = file.listFiles();
+ if (files != null) {
+ for (int i = 0; i < files.length; i++) {
+ files[i].delete();
+ }
+ }
+ }
+
+ public static File pluginRelativeFile(Plugin plugin, String file) throws IOException {
+ Check.checkArg(plugin);
+ Bundle bundle = plugin.getBundle();
+ if (bundle == null)
+ return null;
+ URL url = FileLocator.find(bundle, new Path("."), null); //$NON-NLS-1$
+ if (url == null)
+ return null;
+ url = FileLocator.resolve(url);
+ return new File(url.getPath(), file);
+ }
+
+ /**
+ * Convert the path to a path relative to the base, if possible.
+ * @param rootPath full path to base
+ * @param cpath full path to resource
+ * @return new path (base-relative) or null if not resolvable to base
+ */
+ static public IPath removePrefixFromPath(IPath rootPath, IPath cpath) {
+ if (matchingFirstSegments(rootPath, cpath) == rootPath.segmentCount()) {
+ IPath suffix = cpath.removeFirstSegments(rootPath.segmentCount());
+ return suffix.setDevice(null);
+ }
+ return null;
+ }
+
+ /**
+ * Convert the path to a path in the workspace, if possible.
+ * Either the path comes in as a path pointing inside the
+ * workspace, or we can find a linked resource which aliases
+ * to the same location.
+ * @param cpath full filesystem path to resource
+ * @return new path (workspace-relative) or null if not resolvable to workspace
+ */
+ static public IPath convertToWorkspacePath(IPath cpath) {
+ return convertToWorkspacePath(cpath, false);
+ }
+
+ /**
+ * Convert the path to a path in the workspace, if possible.
+ * Either the path comes in as a path pointing inside the
+ * workspace, or we can find a linked resource which aliases
+ * to the same location.
+ * @param cpath full filesystem path to resource
+ * @param makeCanonical if true, work from the canonical path if possible
+ * (recommended)
+ * @return new path (workspace-relative) or null if not resolvable to workspace
+ */
+ static public IPath convertToWorkspacePath(IPath cpath, boolean makeCanonical) {
+ return convertToWorkspacePath(cpath, makeCanonical, true);
+ }
+ /**
+ * Convert the path to a path in the workspace, if possible.
+ * Either the path comes in as a path pointing inside the
+ * workspace, or we can find a linked resource which aliases
+ * to the same location.
+ * @param cpath full filesystem path to resource
+ * @param makeCanonical if true, work from the canonical path if possible
+ * (recommended)
+ * @param resolveLinks if true, look for project paths which reference files outside
+ * the workspace via links (very slow)
+ * @return new path (workspace-relative) or null if not resolvable to workspace
+ */
+ static public IPath convertToWorkspacePath(IPath cpath, boolean makeCanonical, boolean resolveLinks) {
+ if (!Platform.isRunning() || cpath == null)
+ return null;
+
+ if (makeCanonical) {
+ try {
+ // Since we have a filesystem path, try using the filesystem
+ // and Java's smarter APIs to fix the caps early.
+ // Watch out for the device being set incorrectly, though.
+ String device = cpath.getDevice();
+ cpath = new Path(cpath.toFile().getCanonicalPath()).setDevice(device);
+ } catch (IOException e) {
+ // Something's wrong with the path; just use it as-is
+ }
+ }
+
+ IWorkspaceRoot root = ResourcesPlugin.getWorkspace().getRoot();
+ IFile file = root.getFileForLocation(cpath);
+ if (file != null) {
+ return file.getFullPath().setDevice(null);
+ }
+
+ if (resolveLinks) {
+ // try to see if a linked resource points to this
+ IFile[] files = root.findFilesForLocation(cpath);
+ IPath newPath = null;
+ if (files.length > 0)
+ newPath = files[0].getFullPath().setDevice(null);
+ else {
+ IContainer[] folders = root.findContainersForLocation(cpath);
+ if (folders.length > 0)
+ newPath = folders[0].getFullPath().setDevice(null);
+ }
+ return newPath;
+ }
+
+ return null;
+ }
+
+ /**
+ * Convert the full path to a full path inside the workspace, if possible.
+ * (E.g. change a linked resource to the real full path.)
+ *
+ * Either the path comes in as a path pointing inside the
+ * workspace, or we can find a linked resource which aliases
+ * to the same location.
+ * @param cpath full filesystem path
+ * @return same cpath, new path, or null if not resolvable to workspace
+ */
+ static public IPath convertToWorkspaceLocation(IPath cpath) {
+ if (!Platform.isRunning())
+ return null;
+
+ IWorkspaceRoot root = ResourcesPlugin.getWorkspace().getRoot();
+ IPath rootPath = root.getLocation();
+ IPath newPath = convertToWorkspacePath(cpath);
+ if (newPath == null)
+ return null;
+
+ // convert to full path
+ return rootPath.append(newPath);
+ }
+
+ /**
+ * Variant of routine that works with case-insensitive matching.
+ * @see IPath#matchingFirstSegments(IPath)
+ */
+ public static int matchingFirstSegments(IPath my, IPath anotherPath) {
+ if (my == null || anotherPath == null)
+ return 0;
+ int anotherPathLen = anotherPath.segmentCount();
+ int max = Math.min(my.segmentCount(), anotherPathLen);
+ int count = 0;
+ for (int i = 0; i < max; i++) {
+ if (!my.segment(i).equalsIgnoreCase(anotherPath.segment(i))) {
+ return count;
+ }
+ count++;
+ }
+ return count;
+ }
+
+ /**
+ * Map the given file to a path in the current workspace.
+ * @param file
+ * @return the IFile for the file
+ * @deprecated this function is broken since it doesn't resolve linked resources.
+ */
+ public static IFile convertFileToIFile(IContainer container, File file) {
+ IPath path = new Path(file.getAbsolutePath());
+ IPath rootPath = container.getLocation();
+
+ // this is BUGGY! Case sensitive for some dumb reason
+ //int match = path.matchingFirstSegments(rootPath);
+ int match = matchingFirstSegments(path, rootPath);
+ Check.checkState(match >= rootPath.segmentCount());
+
+ path = path.removeFirstSegments(match);
+ IFile wsFile = container.getFile(path);
+ return wsFile;
+ }
+
+ /**
+ * Map the given file to a path in the current workspace.
+ * @param file
+ * @return the IFile for the file, or null if the file is not in the workspace
+ */
+ public static IFile convertFileToIFile(File file) {
+ IPath path = new Path(file.getAbsolutePath());
+
+ IPath wsPath = convertToWorkspacePath(path, true);
+ if (wsPath != null)
+ return ResourcesPlugin.getWorkspace().getRoot().getFile(wsPath);
+
+ return null;
+
+ /*
+ IWorkspaceRoot root = ResourcesPlugin.getWorkspace().getRoot();
+ IPath rootPath = root.getRawLocation();
+
+ // this is BUGGY! Case sensitive for some dumb reason
+ //int match = path.matchingFirstSegments(rootPath);
+ int match = matchingFirstSegments(path, rootPath);
+ if (match < rootPath.segmentCount())
+ return null;
+
+ path = path.removeFirstSegments(match);
+ IFile wsFile = root.getFile(path);
+
+ return wsFile;
+ */
+ }
+
+ /**
+ * Map the given file to a resource in the current workspace. This only handles
+ * files that map to known workspace resources.
+ * @param file
+ * @return the IResource for the file, or null if the file is not in the workspace or doesn't
+ * exist.
+ */
+ public static IResource convertFileToExistingResource(File file) {
+ IPath path = new Path(file.getAbsolutePath());
+
+ IPath wsPath = convertToWorkspacePath(path, true);
+ if (wsPath != null)
+ return ResourcesPlugin.getWorkspace().getRoot().findMember(wsPath);
+
+ return null;
+ }
+
+ /**
+ * Return the project for the given workspace-relative path.
+ */
+ public static IProject projectForPath(IPath path) {
+ IProject result = null;
+ if (path != null) {
+ IWorkspaceRoot root = ResourcesPlugin.getWorkspace().getRoot();
+ result = root.getProject(path.segment(0));
+ }
+ return result;
+ }
+
+ /**
+ * Read contents of a file into an array
+ * @param file
+ * @param encoding (null = system default)
+ * @return array of text
+ * @throws CoreException wrapping java.io.FileException
+ */
+ public static char[] readFileContents(File file, String encoding) throws CoreException {
+ Check.checkArg(file);
+ FileInputStream fis;
+ try {
+ fis = new FileInputStream(file);
+ return readInputStreamContents(fis, encoding);
+ } catch (IOException e) {
+ throw new CoreException(Logging.newStatus(UtilsPlugin.getDefault(), e));
+ }
+ }
+
+ /**
+ * Read contents of a file into an array
+ * @param is input stream
+ * @param encoding (null is system default)
+ * @return array of text
+ * @throws CoreException wrapping java.io.FileException
+ */
+ public static char[] readInputStreamContents(InputStream is, String encoding) throws CoreException {
+ Check.checkArg(is);
+
+ Reader reader;
+ try {
+ if (encoding != null)
+ reader = new InputStreamReader(is, encoding);
+ else
+ reader = new InputStreamReader(is);
+
+ return readReaderContents(reader);
+ } catch (UnsupportedEncodingException e) {
+ throw new CoreException(Logging.newStatus(UtilsPlugin.getDefault(), e));
+ }
+ }
+
+ /**
+ * Read contents of a file into an array
+ * @param file
+ * @param encoding (null = system default)
+ * @return array of text
+ * @throws CoreException wrapping java.io.FileException
+ */
+ public static char[] readReaderContents(Reader reader) throws CoreException {
+ Check.checkArg(reader);
+ try {
+ char[] buf = new char[1024];
+ StringBuffer sb = new StringBuffer();
+ int len;
+ while ((len = reader.read(buf)) > 0) {
+ sb.append(buf, 0, len);
+ }
+ reader.close();
+ return sb.toString().toCharArray();
+ } catch (UnsupportedEncodingException e) {
+ throw new CoreException(Logging.newStatus(UtilsPlugin.getDefault(), e));
+ } catch (IOException e) {
+ throw new CoreException(Logging.newStatus(UtilsPlugin.getDefault(), e));
+ }
+ }
+
+ /**
+ * Write contents of a file from an array
+ * @param file
+ * @param encoding (null = system default)
+ * @throws CoreException wrapping java.io.FileException
+ */
+ public static void writeFileContents(File file, char[] text, String encoding) throws CoreException {
+ Check.checkArg(file);
+ FileOutputStream fos;
+ try {
+ fos = new FileOutputStream(file);
+ writeOutputStreamContents(fos, text, encoding);
+ } catch (IOException e) {
+ throw new CoreException(Logging.newStatus(UtilsPlugin.getDefault(), e));
+ }
+ }
+
+ /**
+ * Write contents on array to an output stream
+ * @param os output stream
+ * @param encoding (null is system default)
+ * @return array of text
+ * @throws CoreException wrapping java.io.FileException
+ */
+ public static void writeOutputStreamContents(OutputStream os, char[] text, String encoding) throws CoreException {
+ Check.checkArg(os);
+
+ Writer writer;
+ try {
+ if (encoding != null)
+ writer = new OutputStreamWriter(os, encoding);
+ else
+ writer = new OutputStreamWriter(os);
+
+ writeWriterContents(writer, text);
+ } catch (UnsupportedEncodingException e) {
+ throw new CoreException(Logging.newStatus(UtilsPlugin.getDefault(), e));
+ }
+ }
+
+ /**
+ * Write contents of an array to a file
+ * @param file
+ * @param encoding (null = system default)
+ * @throws CoreException wrapping java.io.FileException
+ */
+ public static void writeWriterContents(Writer writer, char[] text) throws CoreException {
+ Check.checkArg(writer);
+ try {
+ try {
+ writer.write(text, 0, text.length);
+ } finally {
+ writer.close();
+ }
+ } catch (UnsupportedEncodingException e) {
+ throw new CoreException(Logging.newStatus(UtilsPlugin.getDefault(), e));
+ } catch (IOException e) {
+ throw new CoreException(Logging.newStatus(UtilsPlugin.getDefault(), e));
+ }
+ }
+
+
+ /**
+ * Returns whether pathSegment is a valid part of a path in a Carbide project.
+ * This checks for file name validity and
+ * name only contains alpha-numeric -or- hyphen -or- underscrore -or- dot characters
+ *
+ * @param pathSegment the segment (file or folder name)
+ * @return true if valid
+ */
+ public static boolean isValidCarbideProjectPathSegment(String pathSegment) {
+ IWorkspace workspace = ResourcesPlugin.getWorkspace();
+ int typeMask = IResource.FILE | IResource.FOLDER;
+ boolean valid = pathSegment.length() == 0 ||
+ workspace.validateName(pathSegment, typeMask).isOK();
+ if (valid) {
+ for (int i = 0; i < pathSegment.length(); i++) {
+ char c = pathSegment.charAt(i);
+ valid = Character.isLetterOrDigit(c) || (c == '-') || (c == '_');
+ if (!valid)
+ break;
+ }
+ }
+
+ return valid;
+ }
+
+ /**
+ * Resolve a workspace-relative path to correct any problems in
+ * capitalization.
+ * @param projectName
+ * @param wsPath workspace-relative path
+ * @return resolved path, as far as actual resources exist (the suffix
+ * may be unchanged if an intervening folder is missing)
+ */
+ public static IPath getCanonicalWorkspacePath(IPath wsPath) {
+ IPath resolvedPath = new Path(""); //$NON-NLS-1$
+ IContainer container = ResourcesPlugin.getWorkspace().getRoot();
+ // flag to consume the rest of the path without lookup
+ boolean failed = false;
+ for (String segment : wsPath.segments()) {
+ if (failed || container == null) {
+ resolvedPath = resolvedPath.append(segment);
+ continue;
+ }
+
+ IResource child = container.findMember(segment);
+ if (child != null) {
+ // found, so correct caps
+ resolvedPath = resolvedPath.append(segment);
+ if (child instanceof IContainer) {
+ container = (IContainer) child;
+ } else {
+ container = null;
+ }
+ } else {
+ // not found: manually search
+ boolean found = false;
+ try {
+ for (IResource member : container.members()) {
+ if (member.getName().equalsIgnoreCase(segment)) {
+ resolvedPath = resolvedPath.append(member.getName());
+ found = true;
+ if (member instanceof IContainer) {
+ container = (IContainer) member;
+ } else {
+ container = null;
+ }
+ break;
+ }
+ }
+ } catch (CoreException e) {
+ // just fail
+ }
+ if (!found) {
+ failed = true;
+ resolvedPath = resolvedPath.append(segment);
+ }
+ }
+ }
+ return resolvedPath;
+ }
+
+ /**
+ * This is an analogue to new Path(String) but avoids some bugs in
+ * the implementation when pathString is a relative path.
+ * @param pathString
+ * @return new Path
+ */
+ public static IPath createPossiblyRelativePath(String pathString) {
+ // canonicalize slashes
+ char[] pathChars = pathString.toCharArray();
+ int offset = 0;
+ for (int i = 0; i < pathChars.length; i++) {
+ if (pathChars[i] == '\\')
+ pathChars[i] = '/';
+ }
+
+ // The bug is, if "./" appears, then "../"'s after it are dropped,
+ // so get rid of "./" early. The result will still be relative.
+ while (offset + 2 <= pathChars.length) {
+ if (pathChars[offset] == '.' && pathChars[offset+1] == '/') {
+ offset += 2;
+ } else {
+ break;
+ }
+ }
+
+ return new Path(new String(pathChars, offset, pathChars.length - offset));
+ }
+
+ /**
+ * Tell if the given path refers to a parent directory (e.g.
+ * contains ".." entries)
+ * @param path
+ * @return true if resolved path contains ".."
+ */
+ public static boolean isPathInParent(IPath path) {
+ // first see if any segments are ".." at all
+ for (int i = 0; i < path.segmentCount(); i++) {
+ if (path.segment(i).equals("..")) { //$NON-NLS-1$
+ // comprehensive check, canonicalizing
+ path = new Path(path.toString());
+ if (path.segmentCount() > 0 && path.segment(0).equals("..")) { //$NON-NLS-1$
+ return true;
+ } else {
+ return false;
+ }
+ }
+ }
+ return false;
+ }
+
+ /**
+ * Recurse the directory, returning files that match the given filter.
+ * The directories "." and ".." are filtered out before the filter sees them.
+ * The filter is passed files and directories, and a directory must
+ * pass the filter to be recursed.
+ * @param dir
+ * @param filter
+ * @param recordDirectories if true, accepted directories are added to the returned list;
+ * otherwise, directories are not added to the file list.
+ * @return array of matching files , never null
+ */
+ public static File[] listFilesInTree(File dir, FileFilter filter, boolean recordDirectories) {
+ List files = new ArrayList();
+ listFilesInTreeHelper(files, dir, filter, recordDirectories);
+ return (File[]) files.toArray(new File[files.size()]);
+ }
+
+ private static void listFilesInTreeHelper(List files, File dir, FileFilter filter, boolean recordDirectories) {
+ if (recordDirectories)
+ files.add(dir);
+
+ File[] allEntries = dir.listFiles();
+ if (allEntries == null)
+ return;
+
+ for (File fileOrDir : allEntries) {
+ if (fileOrDir.getName().equals(".") || fileOrDir.getName().equals("..")) { //$NON-NLS-1$ //$NON-NLS-2$
+ // ignore
+ } else if (fileOrDir.isDirectory()) {
+ if (filter.accept(fileOrDir)) {
+ listFilesInTreeHelper(files, fileOrDir, filter, recordDirectories);
+ }
+ } else if (filter.accept(fileOrDir)) {
+ files.add(fileOrDir);
+ }
+ }
+ }
+
+ public static URL getParentPathURL(URL url) throws CoreException {
+ URL result;
+ try {
+ String string = url.toString();
+ int loc = string.lastIndexOf('/');
+ result = new URL(string.substring(0, loc + 1));
+ } catch (Exception e) {
+ throw new CoreException(Logging.newStatus(UtilsPlugin.getDefault(), e));
+ }
+
+ return result;
+ }
+
+ /**
+ * Wrapper around {@link FileUtils#validateEdit(IFile[], Shell)}
+ * taking a single file. If a modified files multistatus is generated
+ * the single entry for the single file is retrieved and returned.
+ */
+ public static IStatus validateEdit(IFile file, Shell context) {
+ IStatus status = validateEdit(new IFile[] {file}, context);
+ if (!status.isOK()) {
+ if (status.isMultiStatus()) {
+ IStatus[] children = status.getChildren();
+ if (children != null && children.length == 1 &&
+ children[0].getSeverity() == IStatus.WARNING &&
+ children[0].getCode() == MODIFIED_FILES_STATUS) {
+ status = children[0];
+ }
+ }
+ }
+ return status;
+ }
+
+ /**
+ * Wrapper around {@link IWorkspace#validateEdit(IFile[], Object)}
+ * Checks if any of the files have been modified by the validate
+ * operations. If so a MultiStatus is returned with WARNING severity.
+ * The code for the multistatus and each child is MODIFIED_FILES_STATUS
+ * and for each child the message fields is the full workspace
+ * path to the modified file.
+ * @param files
+ * @param context a Shell if UI interaction is allowed
+ * @return OK status, non-OK status from validateEdit, or a
+ * MultiStatus with one child for each modified file.
+ */
+ public static IStatus validateEdit(IFile[] files, Shell context) {
+ List readOnly = new ArrayList();
+ Map timeStamps = new HashMap();
+ for (IFile file : files) {
+ if (file.isReadOnly()) {
+ readOnly.add(file);
+ timeStamps.put(file, file.getModificationStamp());
+ }
+ }
+
+ if (readOnly.isEmpty()) {
+ return Status.OK_STATUS;
+ }
+
+ IStatus status = ResourcesPlugin.getWorkspace().validateEdit(
+ readOnly.toArray(new IFile[readOnly.size()]), context);
+ if (!status.isOK())
+ return status;
+
+ List modified = new ArrayList();
+ for (Map.Entry entry : timeStamps.entrySet()) {
+ Long newTimeStamp = entry.getKey().getModificationStamp();
+ if (!newTimeStamp.equals(entry.getValue())) {
+ modified.add(entry.getKey());
+ }
+ }
+
+ if (modified.size() > 0) {
+ String pluginID = UtilsPlugin.getDefault().getBundle().getSymbolicName();
+ MultiStatus ms = new MultiStatus(pluginID, MODIFIED_FILES_STATUS, "modified files", null);
+ for (IFile file : modified) {
+ String path = file.getFullPath().toString();
+ ms.add(new Status(IStatus.WARNING, pluginID, MODIFIED_FILES_STATUS, path, null));
+ }
+ status = ms;
+ }
+
+ return status;
+ }
+
+ /**
+ * Get the directory used for temporary files.
+ * @return absolute directory for temporary files, which may be the current directory
+ */
+ public static File getTemporaryDirectory() {
+ File dir = new File(System.getProperty("java.io.tmpdir", //$NON-NLS-1$
+ System.getProperty("user.dir", "."))); //$NON-NLS-1$ //$NON-NLS-2$
+ try {
+ return dir.getCanonicalFile();
+ } catch (IOException e) {
+ return dir;
+ }
+ }
+
+ /**
+ * Get the path in a form amenable to comparing with another path.
+ * On Win32 hosts, this lowercases the path. On other hosts, the path is unmodified.
+ * @param path incoming path or null
+ * @return path converted to comparison-friendly format, or null
+ */
+ public static IPath getComparablePath(IPath path) {
+ if (path == null)
+ return null;
+
+ if (Platform.getOS().equals(Platform.OS_WIN32)) {
+ return new Path(path.toOSString().toLowerCase());
+ }
+
+ return path;
+ }
+
+ /**
+ * Get the file extension from path, guaranteed not to return null
+ * @param path IPath
+ * @return String non-null
+ */
+ public static String getSafeFileExtension(IPath path) {
+ String fileExtension = ""; //$NON-NLS-1$
+ if (path != null) {
+ String temp = path.getFileExtension();
+ if (temp != null)
+ fileExtension = temp;
+ }
+
+ return fileExtension;
+ }
+
+ /**
+ * Uses java.io semantics to test existence, because eclipse resources are always case-sensitive,
+ * regardless of the file system.
+ * @param resource {@link IResource}
+ * @return boolean
+ */
+ public static boolean exists(IResource resource) {
+ return resource.getLocation().toFile().exists();
+ }
+}
diff -r ec3f1313ae92 -r 641b65b14318 org.symbian.tools.wrttools.previewer/src/org/symbian/tools/wrttools/previewer/utils/IDisposable.java
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.previewer/src/org/symbian/tools/wrttools/previewer/utils/IDisposable.java Wed Jan 20 16:51:26 2010 -0800
@@ -0,0 +1,32 @@
+/**
+ * Copyright (c) 2009 Symbian Foundation and/or its subsidiary(-ies).
+ * All rights reserved.
+ * This component and the accompanying materials are made available
+ * under the terms of the License "Eclipse Public License v1.0"
+ * which accompanies this distribution, and is available
+ * at the URL "http://www.eclipse.org/legal/epl-v10.html".
+ *
+ * Initial Contributors:
+ * Symbian Foundation - initial contribution.
+ * Contributors:
+ * Description:
+ * Overview:
+ * Details:
+ * Platforms/Drives/Compatibility:
+ * Assumptions/Requirement/Pre-requisites:
+ * Failures and causes:
+ */
+package org.symbian.tools.wrttools.previewer.utils;
+
+ /**
+ * Generic interface for disposable objects
+ *
+ */
+public interface IDisposable {
+
+ /**
+ * Disposes of any resources held by the object.
+ * The object should not be used after dispose has been called.
+ */
+ void dispose();
+}
diff -r ec3f1313ae92 -r 641b65b14318 org.symbian.tools.wrttools.previewer/src/org/symbian/tools/wrttools/previewer/utils/ITimedTask.java
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.previewer/src/org/symbian/tools/wrttools/previewer/utils/ITimedTask.java Wed Jan 20 16:51:26 2010 -0800
@@ -0,0 +1,33 @@
+/**
+ * Copyright (c) 2009 Symbian Foundation and/or its subsidiary(-ies).
+ * All rights reserved.
+ * This component and the accompanying materials are made available
+ * under the terms of the License "Eclipse Public License v1.0"
+ * which accompanies this distribution, and is available
+ * at the URL "http://www.eclipse.org/legal/epl-v10.html".
+ *
+ * Initial Contributors:
+ * Symbian Foundation - initial contribution.
+ * Contributors:
+ * Description:
+ * Overview:
+ * Details:
+ * Platforms/Drives/Compatibility:
+ * Assumptions/Requirement/Pre-requisites:
+ * Failures and causes:
+ */
+package org.symbian.tools.wrttools.previewer.utils;
+
+/**
+ * Interface for use with Logging.timeTask()
+ * @author eswartz
+ *
+ */
+public interface ITimedTask {
+ /** Get label for logging task */
+ public String getLabel();
+
+ /** Run the task */
+ public void run();
+
+}
diff -r ec3f1313ae92 -r 641b65b14318 org.symbian.tools.wrttools.previewer/src/org/symbian/tools/wrttools/previewer/utils/ListenerList.java
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.previewer/src/org/symbian/tools/wrttools/previewer/utils/ListenerList.java Wed Jan 20 16:51:26 2010 -0800
@@ -0,0 +1,81 @@
+/**
+ * Copyright (c) 2009 Symbian Foundation and/or its subsidiary(-ies).
+ * All rights reserved.
+ * This component and the accompanying materials are made available
+ * under the terms of the License "Eclipse Public License v1.0"
+ * which accompanies this distribution, and is available
+ * at the URL "http://www.eclipse.org/legal/epl-v10.html".
+ *
+ * Initial Contributors:
+ * Symbian Foundation - initial contribution.
+ * Contributors:
+ * Description:
+ * Overview:
+ * Details:
+ * Platforms/Drives/Compatibility:
+ * Assumptions/Requirement/Pre-requisites:
+ * Failures and causes:
+ */
+package org.symbian.tools.wrttools.previewer.utils;
+
+import java.util.*;
+
+/**
+ * Utility class for listeners. Implemented with the assumption that
+ * iteration is much more common than adding or removing listeners.
+ *
+ * @param a listener interface
+ */
+public class ListenerList implements Iterable {
+
+ private ArrayList listeners;
+
+ public void add(E listener) {
+ if (listeners == null || !listeners.contains(listener)) {
+ ArrayList newList = new ArrayList();
+ if (listeners != null)
+ newList.addAll(listeners);
+ newList.add(listener);
+ listeners = newList;
+ }
+ }
+
+ public void remove(E listener) {
+ if (listeners == null)
+ return;
+ ArrayList newList = new ArrayList(listeners);
+ newList.remove(listener);
+ listeners = newList;
+ }
+
+ public Iterator iterator() {
+ Iterator result;
+ if (listeners != null) {
+ result = listeners.iterator();
+ }
+ else {
+ // would be nice if this could be a static, but it can't
+ result = new EmptyIterator();
+ }
+ return result;
+ }
+
+ public int size() {
+ return listeners != null? listeners.size() : 0;
+ }
+
+ static class EmptyIterator implements Iterator {
+
+ public boolean hasNext() {
+ return false;
+ }
+
+ public E next() {
+ throw new NoSuchElementException();
+ }
+
+ public void remove() {
+ throw new IllegalStateException();
+ }
+ }
+}
diff -r ec3f1313ae92 -r 641b65b14318 org.symbian.tools.wrttools.previewer/src/org/symbian/tools/wrttools/previewer/utils/Logging.java
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.previewer/src/org/symbian/tools/wrttools/previewer/utils/Logging.java Wed Jan 20 16:51:26 2010 -0800
@@ -0,0 +1,456 @@
+/**
+ * Copyright (c) 2009 Symbian Foundation and/or its subsidiary(-ies).
+ * All rights reserved.
+ * This component and the accompanying materials are made available
+ * under the terms of the License "Eclipse Public License v1.0"
+ * which accompanies this distribution, and is available
+ * at the URL "http://www.eclipse.org/legal/epl-v10.html".
+ *
+ * Initial Contributors:
+ * Symbian Foundation - initial contribution.
+ * Contributors:
+ * Description:
+ * Overview:
+ * Details:
+ * Platforms/Drives/Compatibility:
+ * Assumptions/Requirement/Pre-requisites:
+ * Failures and causes:
+ */
+package org.symbian.tools.wrttools.previewer.utils;
+
+import org.symbian.tools.wrttools.previewer.utils.noexport.Messages;
+
+import org.eclipse.core.runtime.*;
+import org.eclipse.jface.dialogs.ErrorDialog;
+import org.eclipse.swt.widgets.Display;
+import org.eclipse.swt.widgets.Shell;
+import org.osgi.framework.Bundle;
+
+import java.io.PrintStream;
+import java.util.*;
+
+/**
+ * Utilities for plugins.
+ *
+ * All of these take a Plugin parameter, which usually requires a call in the
+ * form:
+ *
+ *
+ * Logging.method(MyPlugin.getDefault(), ...);
+ *
+ *
+ *
+ * If this becomes unwieldly, implement a wrapper method in your plugin class to
+ * access these methods natively:
+ *
+ *
+ *
+ *
+ * class MyPlugin extends Plugin {
+ * ...
+ * void <i>method</i>(...) {
+ * Logging.<i>method</i>(getDefault(), ...);
+ * }
+ * ...
+ * }
+ *
+ *
+ *
+ *
+ *
+ * Then call as:
+ *
+ *
+ *
+ * MyPlugin.<i>method</i>(...);
+ *
+ *
+ *
+ *
+ *
+ * @author eswartz
+ *
+ */
+public class Logging {
+
+ /** Tell whether Logging.timeStart() / Logging.timeEnd() / Logging.timeTask() show results
+ * Can't be final because it's modified from unit tests. */
+ static public boolean SHOW_TIMINGS = false;
+
+ /** List of ILogListener */
+ static private List listeners = new ArrayList(0);
+
+ /** Target for log messages when platform is not running
+ This can't be final, it's set from tests */
+ static public PrintStream consoleLog = System.err;
+ /** Always dump log messages to console? If false, only log when platform not running.
+ * Can't be final because it's modified from unit tests. */
+ static public boolean alwaysLogToConsole = false;
+
+ static public void addListener(ILogListener listener) {
+ listeners.add(listener);
+ }
+
+ static public void removeListener(ILogListener listener) {
+ listeners.remove(listener);
+ }
+
+ /**
+ * Create an IStatus instance eminating from the given plugin
+ * which includes detailed info about the plugin vendor, version, etc.
+ * Every IStatus generated by this class includes this information.
+ *
+ * Adapted from Java Developer's Guide to Eclipse, Ch. 28
+ *
+ * @param plugin
+ * the offending plugin
+ * @param severity
+ * the severity (IStatus.ERROR, IStatus.WARNING, IStatus.INFO)
+ * @param message
+ * the localized error string, or null to use
+ * thr.getLocalizedMessage()
+ * @param thr
+ * the throwable, or null
+ * @return new IStatus object
+ */
+ static public IStatus newStatus(Plugin plugin, int severity,
+ String message, Throwable thr) {
+ if (message == null) {
+ if (thr != null) {
+ message = thr.getLocalizedMessage();
+ }
+ if (message == null) {
+ message = thr.getClass().getName();
+ }
+ }
+
+ MultiStatus vitalInfoStatus;
+
+ if (plugin == null || plugin.getBundle() == null) {
+ return new Status(severity, "???", 0,
+ message, thr);
+ }
+
+ Bundle bundle = plugin.getBundle();
+ String symbolicName = bundle.getSymbolicName();
+ String bundleName = "" + bundle.getHeaders().get("Bundle-Name"); //$NON-NLS-1$
+ String bundleVendor = "" + bundle.getHeaders().get("Bundle-Vendor"); //$NON-NLS-1$
+ String bundleVersion = "" + bundle.getHeaders().get("Bundle-Version"); //$NON-NLS-1$
+
+ vitalInfoStatus = new MultiStatus(symbolicName, severity,
+ message, thr);
+
+ // Put new info in separate status containers to force newlines in
+ // dialog
+ vitalInfoStatus.add(new Status(severity, symbolicName, 0,
+ "Plug-in Vendor: " + bundleVendor, null)); //$NON-NLS-1$
+ vitalInfoStatus.add(new Status(severity, symbolicName, 0,
+ "Plug-in Name: " + bundleName, null)); //$NON-NLS-1$
+ vitalInfoStatus.add(new Status(severity, symbolicName, 0,
+ "Plug-in ID: " + symbolicName, null)); //$NON-NLS-1$
+ vitalInfoStatus.add(new Status(severity, symbolicName, 0,
+ "Plug-in Version: " + bundleVersion, null)); //$NON-NLS-1$
+
+ return vitalInfoStatus;
+ }
+
+ /**
+ * Create an IStatus instance eminating from the given plugin.
+ *
+ * @param plugin
+ * the offending plugin
+ * @param severity
+ * the severity (IStatus.ERROR,WARNING,INFO)
+ * @param message
+ * the localized error string
+ * @return new IStatus object
+ */
+ static public IStatus newStatus(Plugin plugin, int severity, String message) {
+ if (message == null)
+ message = ""; //$NON-NLS-1$
+
+ return newStatus(plugin, severity, message, null);
+ }
+
+
+ /**
+ * Create an IStatus instance wrapping an unwanted exception eminating from
+ * the given plugin.
+ *
+ * @param plugin
+ * the offending plugin
+ * @param thr
+ * the throwable, or null
+ * @return new IStatus object
+ */
+ static public IStatus newStatus(Plugin plugin, Throwable thr) {
+ return newStatus(plugin, IStatus.ERROR, thr.getLocalizedMessage(), thr);
+ }
+
+ /**
+ * Create an IStatus instance without plugin context information
+ * (e.g. for logging)
+ *
+ * @param plugin
+ * the plugin
+ * @param severity
+ * the severity (IStatus.ERROR,WARNING,INFO)
+ * @param message
+ * the localized error string
+ * @param thr
+ * the throwable, or null
+ *
+ * @return new IStatus object
+ */
+ static public IStatus newSimpleStatus(Plugin plugin, int severity, String message, Throwable thr) {
+ return new Status(severity, plugin.getBundle().getSymbolicName(),
+ 0, message, thr);
+ }
+
+ /**
+ * Create an IStatus instance occurring presumably a number of steps up the
+ * call chain (e.g. library code, for which the current plugin is not
+ * known). We report the class name from the stack trace stored in the
+ * exception. (Eclipse doesn't have a mechanism for looking up the plugin
+ * from a class (multiple plugins can have the same class).)
+ *
+ * @param depth
+ * stack depth relative to thr(0 = caller that created thr, 1 =
+ * caller's caller...)
+ * @param severity
+ * the severity (IStatus.ERROR,WARNING,INFO)
+ * @param message
+ * the localized error string
+ * @param thr
+ * the throwable (if null, assume depth refers to caller)
+ *
+ * @return new IStatus object
+ */
+ static public IStatus newSimpleStatus(int depth, int severity, String message, Throwable thr) {
+ StackTraceElement els[];
+ if (thr != null)
+ els = thr.getStackTrace();
+ else {
+ els = new Exception().getStackTrace();
+ depth++;
+ }
+
+ if (depth >= els.length)
+ depth = els.length - 1;
+
+ String klass = els[depth].getClassName();
+ return new Status(severity, klass, 0, message, thr);
+ }
+
+ /**
+ * Create an IStatus instance occurring presumably a number of steps up the
+ * call chain (e.g. library code, for which the current plugin is not
+ * known). We report the class name from the stack trace stored in the
+ * exception. (Eclipse doesn't have a mechanism for looking up the plugin
+ * from a class (multiple plugins can have the same class).)
+ *
+ * @param depth
+ * stack depth relative to thr(0 = caller that created thr, 1 =
+ * caller's caller...)
+ * @param thr
+ * the throwable, or null
+ *
+ * @return new IStatus object
+ */
+ static public IStatus newSimpleStatus(int depth, Throwable thr) {
+ return newSimpleStatus(depth, IStatus.ERROR, thr.getLocalizedMessage(), thr);
+ }
+
+ /**
+ * Tell if plugin configured for debugging and a debug option is enabled
+ *
+ * @param plugin
+ * the offending plugin
+ * @param option
+ * The debug option to test. The plugin's symbolic name is
+ * prepended to the option name, e.g.
+ * "com.nokia.myplugin"+"/"+option
+ * @return true if debugging enabled and option enabled (e.g. defined and
+ * set to "true")
+ */
+ static public boolean isDebugOptionEnabled(Plugin plugin, String option) {
+ if (plugin == null || !plugin.isDebugging())
+ return false;
+ String filter = Platform.getDebugOption(plugin.getBundle()
+ .getSymbolicName()
+ + "/" + option); //$NON-NLS-1$
+ return (filter != null && "true".equalsIgnoreCase(filter)); //$NON-NLS-1$
+ }
+
+ /**
+ * Send a message to the Error Log or stdout if plugin
+ * not defined or not loaded.
+ *
+ * @param plugin
+ * the calling plugin
+ * @param status
+ * the status object
+ *
+ */
+ static public void log(Plugin plugin, IStatus status) {
+
+ for (Iterator iter = listeners.iterator(); iter.hasNext();) {
+ ILogListener listener = (ILogListener) iter.next();
+ listener.logging(status, plugin != null ? plugin.getBundle().getSymbolicName() : null);
+ }
+
+ boolean logToConsole = alwaysLogToConsole;
+ if (plugin != null && plugin.getLog() != null) {
+ plugin.getLog().log(status);
+ } else {
+ logToConsole = true;
+ }
+
+ if (consoleLog != null && logToConsole) {
+ consoleLog.println(status.getMessage());
+ if (status.getPlugin() != null)
+ consoleLog.println(Messages.getString("Logging.FromPlugin")+status.getPlugin()); //$NON-NLS-1$
+ if (status.getException() != null) {
+ consoleLog.println(Messages.getString("Logging.DueToException")); //$NON-NLS-1$
+ status.getException().printStackTrace();
+ }
+ }
+ }
+
+ /**
+ * Send a message to the Error Log or stdout
+ * if a given debug option is enabled.
+ *
+ * @param plugin
+ * the calling plugin, or null
+ * @param option
+ * the debug option to test. The plugin name is prepended to the
+ * option name, e.g. "com.nokia.myplugin"+"/"+option
+ * @param status
+ * the status object
+ * @see Logging#isDebugOptionEnabled(Plugin, String)
+ */
+ static public void logIf(Plugin plugin, String option, IStatus status) {
+ if (!isDebugOptionEnabled(plugin, option))
+ return;
+ log(plugin, status);
+ }
+
+ /**
+ * Utility to display an error dialog reporting an IStatus.
+ *
+ * @param title
+ * title of dialog (if null, use "Error")
+ * @param message
+ * concise error message (if null, use status message or status'
+ * wrapped exception message)
+ * @param status
+ * the offending status
+ */
+ static public void showErrorDialog(String title, String message, final IStatus status) {
+ showErrorDialog(null, title, message, status);
+ }
+
+ /**
+ * Utility to display an error dialog reporting an IStatus.
+ *
+ * @param shell the parent shell
+ * @param title
+ * title of dialog (if null, use "Error")
+ * @param message
+ * concise error message (if null, use status message or status'
+ * wrapped exception message)
+ * @param status
+ * the offending status
+ */
+ static public void showErrorDialog(final Shell shell, String title, String message, final IStatus status) {
+ if (!Platform.isRunning())
+ return;
+
+ if (title == null)
+ title = Messages.getString("Logging.ErrorTitle"); //$NON-NLS-1$
+
+ if (message == null) {
+ // this leads to a lot of redundant text
+ /*if (status != null) {
+ message = status.getMessage();
+ if (message == null) {
+ if (status.getException() != null) {
+ message = status.getException().getLocalizedMessage();
+ if (message == null)
+ message = Messages.getString("Logging.NoMessage"); //$NON-NLS-1$
+ }
+ }
+ }*/
+ message = Messages.getString("Logging.GenericErrorMessage"); //$NON-NLS-1$
+ }
+
+ final String title_ = title;
+ final String message_ = message;
+
+ // yes, syncExec(): this is presumably an important error
+ // that shouldn't wait for cascading failures to complete
+ Display.getDefault().syncExec(new Runnable() {
+ public void run() {
+ ErrorDialog.openError(shell, title_, message_, status);
+ }
+ });
+ }
+ // stack of start times (n.b.: Stack is a Vector and is synchronized)
+ private static Stack timeStack = new Stack();
+ // stack of end times (n.b.: Stack is a Vector and is synchronized)
+ private static Stack timeLabelStack = new Stack();
+
+ private static long lastTime;
+
+ /**
+ * Start timing a task, reported to console if Logging#SHOW_TIMINGS is set.
+ * Up to 16 timed tasks can be nested at time.
+ * @param label
+ */
+ public synchronized static void timeStart(String label) {
+ long currentTime = System.currentTimeMillis();
+ if (SHOW_TIMINGS) {
+ if (currentTime > lastTime + 333 && lastTime != 0) {
+ IStatus status = newSimpleStatus(1, IStatus.INFO, "missing time: " + (currentTime - lastTime) + " ms", null); //$NON-NLS-1$
+ log(UtilsPlugin.getDefault(), status);
+ }
+ IStatus status = newSimpleStatus(1, IStatus.INFO, label + " start...", null); //$NON-NLS-1$
+ log(UtilsPlugin.getDefault(), status);
+ }
+ timeLabelStack.push(label);
+ timeStack.push(currentTime);
+ lastTime = currentTime;
+ }
+
+ /**
+ * Stop timing a task, reporting results to console if Logging#SHOW_TIMINGS is set
+ * @return time elapsed in ms
+ */
+ public synchronized static long timeEnd() {
+ lastTime = System.currentTimeMillis();
+ long elapsed = lastTime - timeStack.pop();
+ String label = timeLabelStack.pop();
+ if (SHOW_TIMINGS) {
+ IStatus status = newSimpleStatus(1, IStatus.INFO, label + " end: " + elapsed + " ms", null); //$NON-NLS-1$ //$NON-NLS-2$
+ log(UtilsPlugin.getDefault(), status);
+ }
+ return elapsed;
+ }
+
+ /**
+ * Time a task and report results if Logging#SHOW_TIMINGS is set.
+ * @param task
+ * @return elapsed time in milliseconds
+ */
+ public synchronized static long timeTask(ITimedTask task) {
+ timeStart(task.getLabel());
+ long elapsed = 0;
+ try {
+ task.run();
+ } finally {
+ elapsed = timeEnd();
+ }
+ return elapsed;
+ }
+}
diff -r ec3f1313ae92 -r 641b65b14318 org.symbian.tools.wrttools.previewer/src/org/symbian/tools/wrttools/previewer/utils/TrackedResource.java
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.previewer/src/org/symbian/tools/wrttools/previewer/utils/TrackedResource.java Wed Jan 20 16:51:26 2010 -0800
@@ -0,0 +1,261 @@
+/**
+ * Copyright (c) 2009 Symbian Foundation and/or its subsidiary(-ies).
+ * All rights reserved.
+ * This component and the accompanying materials are made available
+ * under the terms of the License "Eclipse Public License v1.0"
+ * which accompanies this distribution, and is available
+ * at the URL "http://www.eclipse.org/legal/epl-v10.html".
+ *
+ * Initial Contributors:
+ * Symbian Foundation - initial contribution.
+ * Contributors:
+ * Description:
+ * Overview:
+ * Details:
+ * Platforms/Drives/Compatibility:
+ * Assumptions/Requirement/Pre-requisites:
+ * Failures and causes:
+ */
+package org.symbian.tools.wrttools.previewer.utils;
+
+import org.eclipse.core.resources.IFile;
+import org.eclipse.core.resources.IProject;
+import org.eclipse.core.resources.IResource;
+import org.eclipse.core.resources.IResourceChangeEvent;
+import org.eclipse.core.resources.IResourceChangeListener;
+import org.eclipse.core.resources.IResourceDelta;
+import org.eclipse.core.resources.ResourcesPlugin;
+import org.eclipse.core.runtime.CoreException;
+import org.eclipse.core.runtime.IPath;
+
+/**
+ * Helper class to track changes to a resource handle. To the extent
+ * that Eclipse provides the necessary notification, moves and
+ * renames will be tracked and getResource() will return a
+ * reference to the resource.
+ * A listener interface is provided to give notifications of
+ * moves, content changes, and deletions.
+ * Upon deletion, since this object can no longer provide any
+ * useful servce, the dispose method is automatically called
+ * @author dpodwall
+ *
+ */
+public class TrackedResource implements IDisposable {
+
+ private IResource resource;
+ private long modificationStamp;
+ private IPath resourcePath;
+ private Class resourceClass;
+ private ListenerList listeners = new ListenerList();
+ private ResourceHandler handler;
+
+ public interface IListener {
+ void resourceChanged(TrackedResource resource);
+ /**
+ * Called after a resource has been moved and the
+ * TrackedResource has been updated.
+ * @param oldPath the previous location of the resource
+ */
+ void resourceMoved(TrackedResource resource, IPath oldPath);
+ void resourceDeleted(TrackedResource resource);
+ }
+
+ /**
+ * Initialize with the desired resource and being
+ * listening for changes. Once initialized the initial
+ * IResource shouldn't be kept, call getResource as
+ * needed to get the valid resource handle.
+ */
+ public TrackedResource(IResource resource) {
+ Check.checkArg(resource);
+ this.resource = resource;
+ this.resourceClass = resource.getClass();
+ this.resourcePath = resource.getFullPath();
+ Check.checkState(resourcePath != null);
+ enableTracking(true);
+ }
+
+ /**
+ * Dispose must be called in order to unregister the workspace listener.
+ * It is automatically called if the resource is deleted.
+ */
+ public void dispose() {
+ if (handler != null) {
+ enableTracking(false);
+ resourcePath = null;
+ }
+ }
+
+ /**
+ * Set the tracking status to the desired status and return the
+ * previous state.
+ */
+ public synchronized boolean enableTracking(boolean enable) {
+ boolean wasEnabled = handler != null;
+ if (enable == wasEnabled) {
+ return wasEnabled;
+ }
+
+ if (enable) {
+ if (handler == null) {
+ handler = new ResourceHandler();
+ ResourcesPlugin.getWorkspace().addResourceChangeListener(handler);
+ modificationStamp = resource.getModificationStamp();
+ }
+
+ } else if (handler != null){
+ ResourcesPlugin.getWorkspace().removeResourceChangeListener(handler);
+ handler = null;
+ }
+ return wasEnabled;
+ }
+
+ /**
+ * Get the current resource handle. It will differ from
+ * the constructor argument if the resource moved.
+ * Can return null if the resource was deleted
+ *
+ * If non-null, the value will be compatible with
+ * the original resource. In other words if an IFile
+ * was originally used, this will return an IFile (or subclass)
+ * or null.
+ */
+ public IResource getResource() {
+ return resource;
+ }
+
+ /**
+ * Returns the last seen modification stamp.
+ */
+ public long getLastModificationStamp() {
+ return modificationStamp;
+ }
+
+ /**
+ * Force an update of the cached modification stamp to
+ * the lastest value. This will inhibit notifications for
+ * the same modification stamp value.
+ */
+ public void updateModificationStamp() {
+ try {
+ resource.refreshLocal(0, null);
+ } catch (CoreException x) {
+ UtilsPlugin.log(x);
+ }
+ modificationStamp = resource.getModificationStamp();
+ }
+
+ /**
+ * Convenience routine to return as IFile
+ */
+ public IFile getFile() {
+ IFile result = null;
+ if (resource instanceof IFile) {
+ result = (IFile) resource;
+ }
+ return result;
+ }
+
+ /**
+ * Convenience routine to return resource's project.
+ * If the resource is a project it will return that resource,
+ * otherwise the containing project.
+ */
+ public IProject getProject() {
+ IProject result = null;
+ if (resource != null) {
+ result = resource.getProject();
+ }
+ return result;
+ }
+
+ /**
+ * Listener for change events on the tracked resource.
+ * Note that these events may be delivered on
+ * threads other than the UI thread.
+ */
+ public void addListener(IListener listener) {
+ listeners.add(listener);
+ }
+
+ public void removeListener(IListener listener) {
+ listeners.remove(listener);
+ }
+
+ private void fireResourceChanged() {
+ for (IListener l : listeners) {
+ l.resourceChanged(this);
+ }
+ }
+
+ private void fireResourceMoved(IPath oldPath) {
+ for (IListener l : listeners) {
+ l.resourceMoved(this, oldPath);
+ }
+ }
+
+ private void fireResourceDeleted() {
+ for (IListener l : listeners) {
+ l.resourceDeleted(this);
+ }
+ }
+
+ private void handleDeletion() {
+ fireResourceDeleted();
+ dispose();
+ }
+
+ private void handleMove(IResourceDelta delta) {
+ IPath movedToPath = delta.getMovedToPath();
+ if (movedToPath != null) {
+ IResource newResource = ResourcesPlugin.getWorkspace().getRoot().findMember(movedToPath);
+ if (newResource != null) {
+ // the new resource should be compatible with the previous, e.g.
+ // if we started with an IFile the new one should be an IFile
+ Check.checkState(resourceClass.isInstance(newResource));
+ resource = newResource;
+ modificationStamp = resource.getModificationStamp();
+ IPath oldPath = resourcePath;
+ resourcePath = movedToPath;
+ fireResourceMoved(oldPath);
+ }
+ }
+ }
+
+ private void resourceChanged(IResourceChangeEvent event) {
+ IResourceDelta delta = event.getDelta();
+ if (delta != null && resourcePath != null) {
+ delta = delta.findMember(resourcePath);
+ if (delta != null) {
+ int kind = delta.getKind();
+ switch (kind) {
+ case IResourceDelta.CHANGED:
+ if ((IResourceDelta.CONTENT & delta.getFlags()) != 0) {
+ long currStamp = delta.getResource().getModificationStamp();
+ if (currStamp != modificationStamp) {
+ modificationStamp = currStamp;
+ fireResourceChanged();
+ }
+ }
+ break;
+
+ case IResourceDelta.REMOVED:
+ if ((IResourceDelta.MOVED_TO & delta.getFlags()) != 0) {
+ handleMove(delta);
+ }
+ else {
+ handleDeletion();
+ }
+ break;
+ }
+ }
+ }
+ }
+
+ private class ResourceHandler implements IResourceChangeListener {
+
+ public void resourceChanged(IResourceChangeEvent event) {
+ TrackedResource.this.resourceChanged(event);
+ }
+ }
+}
diff -r ec3f1313ae92 -r 641b65b14318 org.symbian.tools.wrttools.previewer/src/org/symbian/tools/wrttools/previewer/utils/UtilsPlugin.java
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.previewer/src/org/symbian/tools/wrttools/previewer/utils/UtilsPlugin.java Wed Jan 20 16:51:26 2010 -0800
@@ -0,0 +1,106 @@
+/**
+ * Copyright (c) 2009 Symbian Foundation and/or its subsidiary(-ies).
+ * All rights reserved.
+ * This component and the accompanying materials are made available
+ * under the terms of the License "Eclipse Public License v1.0"
+ * which accompanies this distribution, and is available
+ * at the URL "http://www.eclipse.org/legal/epl-v10.html".
+ *
+ * Initial Contributors:
+ * Symbian Foundation - initial contribution.
+ * Contributors:
+ * Description:
+ * Overview:
+ * Details:
+ * Platforms/Drives/Compatibility:
+ * Assumptions/Requirement/Pre-requisites:
+ * Failures and causes:
+ */
+package org.symbian.tools.wrttools.previewer.utils;
+
+import java.util.MissingResourceException;
+import java.util.ResourceBundle;
+
+import org.eclipse.core.runtime.IStatus;
+import org.eclipse.core.runtime.Plugin;
+import org.osgi.framework.BundleContext;
+
+/**
+ * The main plugin class to be used in the desktop.
+ */
+public class UtilsPlugin extends Plugin {
+ //The shared instance.
+ private static UtilsPlugin plugin;
+ //Resource bundle.
+ private ResourceBundle resourceBundle;
+
+ /**
+ * The constructor.
+ */
+ public UtilsPlugin() {
+ super();
+ plugin = this;
+ }
+
+ /**
+ * This method is called upon plug-in activation
+ */
+ public void start(BundleContext context) throws Exception {
+ super.start(context);
+ }
+
+ /**
+ * This method is called when the plug-in is stopped
+ */
+ public void stop(BundleContext context) throws Exception {
+ super.stop(context);
+ plugin = null;
+ resourceBundle = null;
+ }
+
+ /**
+ * Returns the shared instance.
+ */
+ public static UtilsPlugin getDefault() {
+ return plugin;
+ }
+
+ /**
+ * Returns the string from the plugin's resource bundle,
+ * or 'key' if not found.
+ */
+ public static String getResourceString(String key) {
+ ResourceBundle bundle = UtilsPlugin.getDefault().getResourceBundle();
+ try {
+ return (bundle != null) ? bundle.getString(key) : key;
+ } catch (MissingResourceException e) {
+ return key;
+ }
+ }
+
+ /**
+ * Returns the plugin's resource bundle,
+ */
+ public ResourceBundle getResourceBundle() {
+ try {
+ if (resourceBundle == null)
+ resourceBundle = ResourceBundle.getBundle("com.nokia.sdt.utils.UtilsPluginResources"); //$NON-NLS-1$
+ } catch (MissingResourceException x) {
+ resourceBundle = null;
+ }
+ return resourceBundle;
+ }
+
+ static public void log(IStatus status) {
+ Logging.log(plugin, status);
+ }
+
+ static public void log(Throwable thr) {
+ Logging.log(plugin, Logging.newStatus(plugin, thr));
+ }
+
+ static public void log(Throwable thr, String msg) {
+ Logging.log(plugin, Logging.newStatus(plugin, IStatus.ERROR, msg, thr));
+ }
+
+}
diff -r ec3f1313ae92 -r 641b65b14318 org.symbian.tools.wrttools.previewer/src/org/symbian/tools/wrttools/previewer/utils/noexport/Messages.java
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.previewer/src/org/symbian/tools/wrttools/previewer/utils/noexport/Messages.java Wed Jan 20 16:51:26 2010 -0800
@@ -0,0 +1,44 @@
+/**
+ * Copyright (c) 2009 Symbian Foundation and/or its subsidiary(-ies).
+ * All rights reserved.
+ * This component and the accompanying materials are made available
+ * under the terms of the License "Eclipse Public License v1.0"
+ * which accompanies this distribution, and is available
+ * at the URL "http://www.eclipse.org/legal/epl-v10.html".
+ *
+ * Initial Contributors:
+ * Symbian Foundation - initial contribution.
+ * Contributors:
+ * Description:
+ * Overview:
+ * Details:
+ * Platforms/Drives/Compatibility:
+ * Assumptions/Requirement/Pre-requisites:
+ * Failures and causes:
+ */
+package org.symbian.tools.wrttools.previewer.utils.noexport;
+
+import java.util.MissingResourceException;
+import java.util.ResourceBundle;
+
+/**
+ * @author eswartz
+ *
+ */
+public class Messages {
+ private static final String BUNDLE_NAME = "com.nokia.sdt.utils.noexport.messages";//$NON-NLS-1$
+
+ private static final ResourceBundle RESOURCE_BUNDLE = ResourceBundle
+ .getBundle(BUNDLE_NAME);
+
+ private Messages() {
+ }
+
+ public static String getString(String key) {
+ try {
+ return RESOURCE_BUNDLE.getString(key);
+ } catch (MissingResourceException e) {
+ return '!' + key + '!';
+ }
+ }
+}
diff -r ec3f1313ae92 -r 641b65b14318 org.symbian.tools.wrttools.previewer/src/org/symbian/tools/wrttools/previewer/utils/noexport/messages.properties
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.previewer/src/org/symbian/tools/wrttools/previewer/utils/noexport/messages.properties Wed Jan 20 16:51:26 2010 -0800
@@ -0,0 +1,23 @@
+Check.RuntimeError=Runtime Error
+Check.ArgumentIsNull=argument is null
+Check.ArgumentIsInvalid=argument is invalid
+Check.ObjectIsInconsistent=object state is inconsistent
+Check.ApiAssertionFailed=assertion on API contract failed
+Logging.ErrorTitle=Error
+Logging.FromPlugin=plugin:
+Logging.DueToException=exception:
+Logging.NoMessage=???
+Logging.GenericErrorMessage=An error has occurred.\nPlease see the Error Log for more details.
+Message.Error=error:
+Message.Warning=warning:
+QueryWithBooleanPrefDialog.1=Don't ask again
+TextUtils.Conjunctions=(in|to|of|and|or|but|if|as)
+SimpleSubstitutionEngine.UnknownVariable=unknown variable ''{0}''
+SimpleSubstitutionEngine.InvalidSubstitution=invalid substitution of variable ''{0}'' with value ''{1}''
+NotifyWithBooleanPrefDialog.DoNotNotifyAgain=Do not ¬ify me again
+FormEditorEditingContext.cantShowUndo=Unable to show undo location.
+EditingContextOperation.cantShowCommandLocation=Unable to display the location for the '{0}' command.
+EditingContextOperation.errorDialogTitle=Error
+ProjectFolderSelectionDialog.SelectFolderDescriptionLabel=Select a folder:
+ProjectFolderSelectionDialog.SelectFolderTitle=Select a folder
+DirectorySelectorWithHistory.BrowseLabel=Browse...
\ No newline at end of file
diff -r ec3f1313ae92 -r 641b65b14318 org.symbian.tools.wrttools.previewer/wrt.xml
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.tools.wrttools.previewer/wrt.xml Wed Jan 20 16:51:26 2010 -0800
@@ -0,0 +1,2847 @@
+
+
+
+
+
+ The widget engine provides a set of system information (SystemInfo) API services. The SystemInfo Service API allows a widget to access a device's properties and to control certain device features. The API is implemented in a plug-in module and it is integrated into the WRT environment.
+ To use the SystemInfo APIs, each widget must load the plug-in module explicitly by defining the following HTML code in its main HTML document
+
+
+
+
+
+ The widget object is a built-in JavaScript object in the widget engine.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This is a read-only property that returns an integer indicating the current battery level.
+ The returned value is in the range of 0 to 100 as a percentage of the maximum battery level.
+
+
+
+
+
+
+
+ The onshow property is an event handler for the event of when a widget is switching from the background to the foreground. In other words, when an opened widget gains focus, the assigned callback function will be called.
+
+
+
+
+
+
+
+
+
+ The onhide property is an event handler for the event of when a widget is switching from the foreground to the background. In other words, when a running widget loses focus, the assigned callback function will be called.
+
+
+
+
+
+
+
+
+
+
+ isrotationsupported is a read-only property that returns a Boolean value determining if the device supports landscape and portrait screen orientations.
+ If the value is true, the device supports both landscape and portrait screen orientations.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The openURL method opens a specified link in the Web Browser for S60 in the stand-alone mode. The widget remains open but is sent to the background.
+
+
+ A compact string specifying a link to a resource to be opened. The URL string format is compliant with the RFC-1738 specification and must be encoded if it contains non-ASCII characters.
+
+
+
+
+
+
+
+
+
+
+ The setPreferenceForKey method allows a key to be stored along with its associated preference. The arguments are like name and value pairs. The preference value for the key is stored persistently, so if the widget or device is restarted, the value is retained. However, the values stored by a widget are removed when a widget is uninstalled from the device. This includes the case when a widget is reinstalled; where the old widget is uninstalled, the new widget is installed.
+ An existing preference can be overwritten with a new value by simply calling the method with the same key and new value.
+
+
+
+ A short text string defined as the name of the preference to be stored.
+
+
+ A compact string specifying a link to a resource to be opened. The URL string format is compliant with the RFC-1738 specification and must be encoded if it contains non-ASCII characters.
+
+
+
+
+
+
+
+
+
+
+
+ The preferenceForKey method allows a previously stored preference to be restored.
+
+
+
+ A text string specifying the name that represents the preference to be restored.
+
+
+
+
+
+
+
+
+
+
+
+
+ The widget's view is composed by HTML elements such as text display area, buttons, edit fields, and so on. The appearance of these HTML elements can be dynamically changed. For example, they can be shown or hidden dynamically using the HTML DOM style object to set the display property to "block" or "none" respectively.
+
+
+ A text string defining a desired transition mode. Currently the only supported transition mode is "fade", which causes the widget's view changing in fading mode.
+
+
+
+
+
+
+
+
+
+
+
+
+ The performTransition method operates as a screen update command, which tells the widget UI framework to update the widget screen. It performs the animation while the widget's view is being changed. Currently, only fading animation mode is supported.
+
+
+
+
+
+
+
+
+
+ The navigation mode in a widget can be toggled between a cursor and a tabbed navigation mode. By default, the browsing mode of a widget is set to use a cursor (pointer). The setNavigationEnabled method is used for changing the widget's navigation mode.
+ The argument navigationType is of Boolean type and can be set to true or false to toggle the navigation mode between the cursor mode and the tab mode respectively.
+
+
+
+ Set to true to enable the cursor navigation mode, and set to false to enable the tabbed navigation mode.
+
+
+
+
+
+
+
+
+
+
+
+
+ The setDisplayLandscape method changes the orientation of a widget's screen to the landscape mode.
+
+
+
+
+
+
+
+ The openApplication method enables a widget to launch an S60 mobile application in the stand-alone mode.
+
+
+
+
+ A hexadecimal number that specifies the UID of the S60 application to be activated. See the table below for example application UIDs.
+
+
+
+ A text string defining a possible argument string that is accepted by the S60 application to be activated.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The setDisplayPortrait method changes the orientation of a widget's screen to the portrait mode.
+
+
+
+
+
+
+
+
+
+
+ The menu object is supported since WRT version 1.0.
+
+
+
+
+
+
+
+
+ The menu object is a built-in object in the widget engine. It is extended from the window object to
+ provide widget-specific APIs for manipulating widget's options menu and softkeys.
+ The menu object can be accessed via the window object window.menu or just simply menu. Thus, in the
+ WRT environment, the term menu is a reserved keyword and should not be used as a user-defined global
+ variable name for other type of objects.
+ A widget's options menu can be constructed using the menu object. The options menu is automatically
+ associated with the device's left softkey and it cannot be reassigned to associate with another
+ softkey (for example, the right softkey). The label of the options menu (the left softkey) is the
+ system-defined term in the current used system language (for example, Options for English).
+ Thus, the left softkey label cannot be changed.
+
+
+
+
+
+
+
+
+
+
+ The onShow property of the menu object is an event handler for the event of when the options menu is open. In other words, when the end user presses the left softkey, the system will fire an event and a widget can catch the event by providing a callback function.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Call the append method to add a menu item to the top level of the options menu list.
+ Menu items are shown on the options menu list in the order in which they are appended.
+ For more general information on constructing an options menu.
+
+
+
+ This is an instance of the MenuItem object which is being added to the top level of the options menu
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Call the remove method to remove a menu item from the top level of the options menu list. If the removed menu item has a cascading submenu in it, the submenu will also be removed.
+
+
+
+ This is an instance of the MenuItem object which is being removed from the top level of the options menu list.
+
+
+
+
+
+
+
+
+
+
+
+
+ Call the getMenuItemById method with a specified menu item's identifier to retrieve the handle of the menu item instance.
+
+
+
+ This is the identifier of an existing menu item whose handle is being retrieved.
+
+
+
+
+
+
+
+
+
+
+
+
+ Call the getMenuItemByName method with a specified menu item's label to retrieve the handle of the menu item instance.
+
+
+
+ This is the identifier of an existing menu item whose handle is being retrieved.
+
+
+
+
+
+
+
+
+
+
+
+
+ Call the setRightSoftkeyLabel method to customize the label and the operation associated with the right softkey.
+ By default, the right softkey of a device is assigned to the "Exit" function, which terminates a running widget. The default label depends on the current used system language (Exit for English).
+
+
+
+ A text string specifies the label to be shown on the right softkey.
+
+
+
+ A reference to the callback function, which will be called by the system when the right softkey is pressed.
+
+
+
+
+
+
+
+
+
+
+
+
+ Call the showSoftkeys method to display the softkey pane at all times.
+ By default, the device's softkey pane is hidden. The softkey pane is shown either by programmatically calling the showSoftkeys method or when the end user presses one of the softkeys.
+
+
+
+
+
+
+
+
+
+
+ Call the hideSoftkeys method to hide the softkey pane.
+ By default, the device's softkey pane is hidden. The softkey pane is shown automatically when the end user presses one of the softkeys.
+
+
+
+
+
+
+
+
+
+
+ Call the clear method to delete all the menu items in the options menu pane. This operation will also clear all submenus if such exist
+
+
+
+
+
+
+
+
+
+
+
+ The MenuItem object is supported since WRT version 1.0.
+
+
+
+
+
+
+
+
+ Creates a new instance of an Enumerator object.
+
+
+
+
+
+
+ A text string that defines the label for the menu item.
+
+
+ A unique integer that identifies the menu item.
+
+
+
+
+
+
+
+
+
+
+
+ The onSelect property of the MenuItem object is an event handler for the event of when the menu item is selected. In other words, when the end user opens the options menu and selects a menu item either from the top-level menu list or from a submenu list, the system will fire an event and a widget can catch the event by providing a callback function.
+
+
+
+
+
+
+
+
+
+
+
+
+ Call the append method to add a child menu item to the parent menu item in the options menu list. This results in the creation of a submenu list in the menu tree. Use this method to create a cascading submenu when needed.
+ Menu items are shown on the options menu list in the order in which they are appended.
+
+
+
+ This is an instance of the MenuItem object which is being added to the parent menu item. See also the menu.append method description for instructions on how to append a menu item to the top level of the options menu list.
+
+
+
+
+
+
+
+
+
+
+
+
+ Call the remove method to remove a child menu item and its children (if any) from the parent menu item.
+
+
+
+ This is an instance of the MenuItem object which is being removed from the parent menu item. See also the menu.remove method description for instructions on how to remove a menu item from the top level of the options menu list.
+
+
+
+
+
+
+
+
+
+
+
+
+ Call the setDimmed method to show or hide an existing menu item. By default, a menu item is shown when it is appended to the options menu.
+
+
+
+ true to show the menu item, and false to hide the menu item.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Each key represents one piece of contact information, such as first name, last name, home phone number, or email address. For each contact, GetList returns as many keys as has been defined for that contact.
+
+
+
+
+
+
+
+
+
+
+ Label
+
+
+
+
+
+
+
+
+ Value
+
+
+
+
+
+
+
+
+ FirstName
+
+
+
+
+
+
+
+
+ LastName
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Item
+
+
+
+
+
+
+
+
+
+
+ CalendarName
+
+
+
+
+
+
+
+
+ LocalId
+
+
+
+
+
+
+
+
+ InstanceStartTime
+
+
+
+
+
+
+
+
+
+
+ Unique identifier of the contact.
+
+
+
+
+
+
+
+
+ Each key represents one piece of contact information, such as first name, last name, home phone number, or email address. For each contact, GetList returns as many keys as has been defined for that contact.
+
+
+
+
+
+
+
+
+ Name of the group.
+
+
+
+
+
+
+
+
+ Contains the IDs of the contacts that belong to the group.
+
+
+
+
+
+
+
+
+ URI of the database.
+
+
+
+
+
+
+
+
+
+
+ AppManager:
+ Contains a unique ID for the application binary (EXE or DLL).
+
+
+
+
+
+
+
+
+ AppManager:
+ Contains the path of the application. For example, c:\sys\bin\calculator.exe.
+
+
+
+
+
+
+
+
+ AppManager:
+ Contains the title of the application.
+
+
+
+
+
+
+
+
+ AppManager:
+ Contains the short title of the application. For example, the short caption may be displayed beneath an icon on the mobile device.
+
+
+
+
+
+
+
+
+ AppManager:
+ Contains the name of the application. For example, the package name may be displayed in a menu on the mobile device.
+
+
+
+
+
+
+
+
+ AppManager:
+ Contains the version of the application. The version consists of two parts: Major, Minor.
+ For example, 1.01, where 1 is the major part and .02 is the minor part.
+
+
+
+
+
+
+
+
+ AppManager:
+ Contains the vendor of the application.
+
+
+
+
+
+
+
+
+ AppManager:
+ Contains the drive where the application is installed.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Iterator
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ reset
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ getNext
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ result
+
+
+
+
+
+
+
+
+
+
+
+ Return value
+
+
+
+
+
+
+
+
+ This is a number that specifies a predefined error code.
+
+
+
+
+
+
+
+
+ This is a text string that describes the error.
+
+
+
+
+
+
+
+
+ This is a number used as an identification to match transactions started with an asynchronous call to one or more calls it generates to callback. This is only valid for Asynchronous invocations.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This Service API allows widgets to:
+ <p>
+ <ul>
+ <li>access, create, and manage calendars/calendar entries,</li>
+ <li>access and manage information about contacts,</li>
+ <li>access and manage information about landmarks and landmark categories,</li>
+ <li>add, read, and delete logging events such as call logs, messaging logs, and so forth,</li>
+ <li>retrieve information (metadata) about the media files stored in the Media Gallery of a device.</li>
+ </ul>
+ </p>
+ <p>
+ To use the <code>IDataSource</code> Service API, your widget must first create a service object for it using the <code>device.getServiceObject()</code> method.
+ </p>
+ <p>
+ Use <code>Service.Calendar</code> or <code>Service.Contact</code> or <code>Service.Landmarks</code> or <code>Service.Logging</code> or <code>Service.MediaManagement</code> to identify the service provider and <code>IDataSource</code> to identify the supported interface:
+ </p>
+
+ <pre>var so = device.getServiceObject("Service.Calendar", "IDataSource");</pre>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <p><b>Calendar:</b>
+ The <code>GetList</code> method retrieves a list of available calendars or calendar entries. Calendar entries are retrieved from the specified calendar or, if no calendar is specified, from the default one.
+ This is a synchronous method.</p>
+
+ <p><b>Contacts:</b>
+ The <code>GetList</code> method retrieves a list of contacts, contact groups, or contacts databases. Contacts and contact groups are retrieved from the specified contacts database or, if no database is specified, from the default one.
+ This method can be called both synchronously and asynchronously.</p>
+
+ <p>Note: Calls that retrieve a list of databases must always be synchronous.</p>
+
+ <p><b>Landmarks:</b>
+ The <code>GetList</code> method retrieves information about landmarks, landmark categories, or landmark databases. Landmarks and landmark categories are retrieved from the specified landmark database or, if no database is specified, from the default one.
+ This method can be called both synchronously and asynchronously.</p>
+
+ <p>Note: For retrieving information about databases, only synchronous GetList is supported.<p/>
+
+ <p><b>Logging:</b>
+ The <code>GetList</code> method retrieves an iterable list of entries from the log event database. The database contains two types of entries, log entries (all entries) and recent log entries (a subset of all log entries).
+ This method can be called both synchronously and asynchronously.</p>
+
+ <p><b>Media Management:</b>
+ The <code>GetList</code> method retrieves a list of media information objects from the Media Gallery of the S60 device. Each object contains information about a single media file.
+ This is an asynchronous method.</p>
+
+
+
+
+
+ This is an object that specifies what type of calendar/location/landmark/log event information is returned and how the returned information is sorted.
+
+
+
+
+
+ The callback argument is the name of the method that is executed when an asynchronous GetList call has results or status information to return. You must define this method separately.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <p><b>Calendar:</b>
+ The <code>Add</code> method creates a new calendar on the device or adds an entry to a calendar. In the latter case, if an entry with the same LocalId already exists in the calendar, it is modified accordingly. You can thus use this method to both add and update calendar entries. The entry is added to the specified calendar or, if no calendar is specified, to the default one. If the default calendar does not exist, it is created.
+ This is a synchronous method.</p>
+
+ <p><b>Contact:</b>
+ The <code>Add</code> method adds a contact or contact group to a contacts database. If the contact or contact group already exists in the database, it is replaced with the new entry. You can thus use this method to both add and edit contacts and contact groups. The information is added to the specified database or, if no database is specified, to the default one. If the default database does not exist, it is created.
+ This method can be called both synchronously and asynchronously.</p>
+
+ <p><b>Landmarks:</b>
+ The <code>Add</code> method adds a new landmark or landmark category to a landmark database. You can also use this method to edit an existing landmark or landmark category.
+ This is a synchronous method.</p>
+
+ <p><b>Logging:</b>
+ The <code>Add</code> method adds an event (entry) to the event log database.
+ This method can be called both synchronously and asynchronously.</p>
+
+
+
+
+
+ This is an object that specifies the calendar/contact/landmark/log to create or to add or update.
+
+
+
+
+
+ The callback argument is the name of the method that is executed when an asynchronous Add call has results or status information to return. You must define this method separately.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <p><b>Calendar:</b>
+ The <code>Delete</code> method deletes a calendar from the device or one or more entries from a calendar. Entries are deleted from the specified calendar or, if no calendar is specified, from the default one.
+ For deleting a calendar, this method is called synchronously. For deleting calendar entries, this method can be called both synchronously and asynchronously.</p>
+
+ <p><b>Contacts:</b>
+ The <code>Delete</code> method deletes one or more contacts or contact groups from a contacts database. The information is deleted from the specified database or, if no database is specified, from the default one.
+ This method can be called both synchronously and asynchronously</p>
+
+ <p><b>Landmark:</b>
+ The <code>Delete</code> method deletes a landmark or landmark category from a landmark database.
+ Note: You cannot delete landmark databases.
+ This is a synchronous method.</p>
+
+ <p><b>Logging:</b>
+ The <code>Delete</code> method deletes an event (entry) from the event log database.
+ This method can be called both synchronously and asynchronously.</p>
+
+
+
+
+
+ This is an object that specifies which calendar/calendar entries/contacts/contact groups/landmark/landmark category/event to delete from the database.
+
+
+
+
+
+ The callback argument is the name of the method that is executed when an asynchronous Delete call has results or status information to return. You must define this method separately.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <p><b>Calendar:</b>
+ The <code>Import</code> method imports entries into a calendar. The information must be imported from an iCal or vCal file. For more information about these two formats, see the Calendar Service overview page.
+ This method can be called both synchronously and asynchronously.</p>
+
+ <p><b>Contact:</b>
+ The <code>Import</code> method imports a contact to a contacts database. The information must be imported from a vCard file.
+ This method can be called both synchronously and asynchronously.</p>
+
+ <p><b>Landmark:</b>
+ The <code>Import</code> method imports a set of landmarks to a landmark database.
+ This is a synchronous method.</p>
+
+
+
+
+
+
+ This is an object that specifies the calendar entries/contacts/landmarks to import.
+
+
+
+
+
+ The callback argument is the name of the method that is executed when an asynchronous Import call has results or status information to return. You must define this method separately.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <p><b>Calendar:</b>
+ The <code>Export</code> method exports entries from a calendar. The information is exported to an iCal or vCal file. For more information about these two formats, see the Calendar Service overview page.
+ This method can be called both synchronously and asynchronously.</p>
+
+ <p><b>Contact:</b>
+ The <code>Export</code> method exports a contact from a contacts database. The information is exported to a vCard file.
+ This method can be called both synchronously and asynchronously</p>
+
+ <p><b>Landmark:</b>
+ The <code>Export</code> method exports a set of landmarks from a landmark database.
+ This is a synchronous method.</p>
+
+
+
+
+
+ This is an object that specifies the calendar/contacts/landmarks entries to export.
+
+
+
+
+
+ The callback argument is the name of the method that is executed when an asynchronous Export call has results or status information to return. You must define this method separately.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <p><b>Calendar:</b>
+ The <code>RequestNotification</code> method notifies the client when entries are created, updated, or deleted in the specified calendar. If no calendar is specified, the default calendar is used.
+ This is an asynchronous method.</p>
+
+ <p><b>Logging:</b>
+ The <code>RequestNotification</code> method registers the widget to receive notifications of changes to the event log.
+ This is an asynchronous method.</p>
+
+
+
+
+
+ This is an object that specifies which calendar, calendar entries and event log to monitor for changes and when.
+
+
+
+
+
+ The callback argument is the name of the method that is executed when an asynchronous 'RequestNotification' call has results or status information to return. You must define this method separately.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <p><b>Calendar:</b>
+ The <code>Cancel</code> method cancels an ongoing asynchronous call made with a Calendar Service API method.
+ This is a synchronous method.</p>
+
+ <p><b>Contact:</b>
+ The <code>Cancel</code> method cancels an outstanding asynchronous call made with a Contacts Service API method.
+ This is a synchronous method.</p>
+
+ <p><b>LandMark:</b>
+ The <code>Cancel</code> method cancels an ongoing asynchronous call made with a Landmarks Service API method.
+ This is a synchronous method.</p>
+
+ <p><b>Logging:</b>
+ The <code>Cancel</code> method cancels an ongoing asynchronous call made with a Landmarks Service API method.
+ This is a synchronous method.</p>
+
+
+
+
+
+ This is an object with the TransactionID property (number). criteria.TransactionID specifies the transaction ID of the asynchronous call to cancel. The transaction ID is the result.TransactionID value that was returned as part of the result of the initial call.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <p><b>Calendar:</b>
+ The <code>Organise</code> method adds contacts to a contact group (association) or removes contacts from a contact group (disassociation). The operation is performed on the specified database or, if no database is specified, on the default one.
+ This method can be called both synchronously and asynchronously.</p>
+
+ <p><b>Landmark:</b>
+ The <code>Organise</code> method adds landmarks to a landmark category (association) or removes landmarks from a landmark category (disassociation). The same landmark can belong to multiple categories or to no category.
+ This is a synchronous method.</p>
+
+
+
+
+
+ This is an object that specifies which contact group/landmarks to organize and how.
+
+
+
+
+
+ The callback argument is the name of the method that is executed when an asynchronous Organise call has results or status information to return. You must define this method separately.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The <code>New</code> method creates an empty landmark or landmark category item. You can use the new item as a template.
+ This is a synchronous method.
+
+
+
+
+
+ This is an object that specifies the type of item to create
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <p>The AppManager Service API allows widgets to access and launch applications on a mobile device.</p>
+ <p>The API is integrated with WRT through the <code>device</code> object.</p>
+ <p>To use the AppManager Service API, your widget must first create a service object for it using the <code>device.getServiceObject()</code> method.</p>
+ <p>Use <code>Service.AppManager</code> to identify the service provider and <code>IAppManager</code> to identify the supported interface:</p>
+
+ <pre>var so = device.getServiceObject("Service.AppManager", "IAppManager");</pre>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The <code>GetList</code> method retrieves an iterable list of either user-installed applications or all applications on the mobile device, regardless of whether they were preinstalled or installed by the user.
+ This is a synchronous method.
+
+
+
+
+
+ This is an object that specifies what information is returned about the applications on the device.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The <code>Cancel</code> method cancels an outstanding asynchronous call.
+ If a cancel is sent, but the asynchronous call has already been completed, then <code>result.Errorcode</code> is set to 0 (success).
+ This is a synchronous method.
+
+
+
+
+
+ This is an object with the <code>TransactionID</code> property (number).
+ <code>criteria.TransactionID</code> specifies the transaction ID of the asynchronous call to cancel.
+ The transaction ID is the result.TransactionID value that was returned as part of the result of the initial call.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The <code>LaunchApp</code> method launches an application based on a unique ID for the application (UID).
+ It also provides a way to open a specific document (by specifying a document path), even if it is not the default file type for the application being launched.
+ For example, you can specify a path to a document with a .txt extension to open in WordPad, even though Notepad is the default application for .txt files.
+ The application can be launched as chained (embedded) or stand-alone.
+
+ This method can be called both synchronously and asynchronously.
+
+
+
+
+
+
+ The criteria object specifies the application to launch.
+ The criteria object has three main properties: ApplicationID, CmdLine, and Options
+
+
+
+
+
+ The callback argument is the name of the method that is executed when an asynchronous LaunchApp call has status information to return. You must define this method separately.
+ This argument is used only with an asynchronous LaunchApp call.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The <code>LaunchDoc</code> method launches an application based on a given document.
+ This method automatically determines which application to launch for the specified document.
+ The application can be launched as chained (embedded) or stand-alone.
+
+ This method can be called both synchronously and asynchronously.
+
+
+
+
+
+
+ This is an object that specifies which application to launch.
+
+
+
+
+
+ The callback argument is the name of the method that is executed when an asynchronous LaunchDoc call has status information to return. You must define this method separately.
+ This argument is used only with an asynchronous LaunchDoc call.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <p>The Messaging Service API allows widgets to send, retrieve, and manage messages using the Messaging Center of a device.</p>
+ <p>The API is integrated into WRT through the <code>device</code> object.</p>
+
+ <p>To use the Messaging Service API, your widget must first createa service object for it using the <code>device.getServiceObject()</code> method.</p>
+ <p>Use <code>Service.Messaging</code> to identify the service provider and <code>IMessaging</code> to identify the supported interface:</p>
+
+ <pre>var so = device.getServiceObject("Service.Messaging", "IMessaging");</pre>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The <code>GetList</code> method retrieves a list of messaging objects from the Messaging Center of the S60 device.
+ Each object contains messaging information, that is, header and content data for a single message.
+ This is a synchronous method.
+ The criteria object specifies what messaging information is returned and how the returned information is sorted.
+ The GetList method returns an object that contains the requested messaging information, an error code, and an error message.
+ To access information about individual messages, iterate through the list of objects contained in ReturnValue attribute of the returned object.
+
+
+
+
+
+ This is an object that specifies the search criteria.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <p>
+ The <code>RegisterNotification</code> method registers the widget to receive notifications of new incoming messages.
+ For each new message, the method returns the header information of that message.
+ This is an asynchronous method.
+ </p>
+
+ <pre>result = so.IMessaging.RegisterNotification(criteria, callback);</pre>
+
+ <p>
+ Criteria object that specifies the request for notification of new messages.
+ The object must contain the Type property (string), and this property must contain the value <code>NewMessage</code>.
+ The callback argument is the name of the method that is executed when <code>RegisterNotification</code> has results or status information to return.
+ You must define this method separately.
+ The <code>RegisterNotification</code> method returns an object that contains the initial return value for the asynchronous call it started.
+ The actual notification information is returned by the callback method in the ReturnValue property of its result object.
+ <code>RegisterNotification</code> retrieves new message updates until cancelled with <code>CancelNotification</code> (or <code>Cancel</code>).
+ You can therefore have only one <code>RegisterNotification</code> call (one instance) pending or in use at any given time.
+ </p>
+
+
+
+
+
+ Criteria object specifies the type and details of the message to send.
+
+
+
+
+ The callback argument is the name of the method that is executed when an asynchronous Send call has status information to return. You must define this method separately.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <p>
+ The <code>CancelNotification</code> method cancels notification of new incoming messages.
+ This is a synchronous method.
+ </p>
+
+ <pre>result = so.IMessaging.CancelNotification(criteria);</pre>
+
+ <p>
+ The criteria object specifies the request for cancelling notification of new messages.
+ The object must contain the Type property (string), and this property must contain the value <code>NewMessage</code>.
+ The <code>CancelNotification</code> method returns an object that contains an error code and an error message.
+ </p>
+
+
+
+
+
+ The criteria object specifies the request for cancelling notification of new messages. The object must contain the Type property (string), and this property must contain the value "NewMessage".
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <p>
+ The <code>Send</code> method sends an SMS or MMS message.
+ This method can be called both synchronously and asynchronously.
+ </p>
+
+ <p>
+ For synchronous calls:
+ </p>
+
+ <pre>result = so.IMessaging.Send(criteria);</pre>
+
+ <p>
+ For asynchronous calls:
+ </p>
+
+ <pre>result = so.IMessaging.Send(criteria, callback);</pre>
+
+ <p>
+ Criteria object specifies the type and details of the message to send.
+ The callback argument is the name of the method that is executed when an asynchronous <code>Send</code> call has status information to return.
+ You must define this method separately.
+ If synchronous, the method returns an object that contains an error code and an error message.
+ If asynchronous, the method returns an object that contains a transaction ID for the callback instance, an error code, and an error message.
+ When the asynchronous call has completed, callback returns an object that contains an error code and an error message.
+ </p>
+
+
+
+
+
+ Criteria object specifies the type and details of the message to send.
+
+
+
+
+ The callback argument is the name of the method that is executed when an asynchronous Send call has status information to return. You must define this method separately.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The <code>Cancel</code> method cancels an outstanding asynchronous <code>Send</code> or <code>RegisterNotification</code> call.
+ To cancel a <code>RegisterNotification</code> call, use <code>CancelNotification</code> instead, as it provides a more convenient way of doing this.
+ This is a synchronous method.
+ The criteria object has <code>TransactionID</code> property which specifies the transaction ID of the <code>Send</code> or <code>RegisterNotification</code> call to cancel.
+ The transaction ID is the same <code>TransactionID</code> value that was returned as part of the result of the initial call.
+ The <code>Cancel</code> method returns an object that contains an error code and an error message.
+
+
+
+
+
+ The criteria object has TransactionID property which specifies the transaction ID of the Send or RegisterNotification call to cancel. The transaction ID is the same TransactionID value that was returned as part of the result of the initial call.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <p>
+ The <code>ChangeStatus</code> method changes the read status of a message.
+ The status can be "Read", "Unread", "Replied", or "Forwarded".
+ This is a synchronous method.
+ </p>
+
+ <pre>result = so.IMessaging.ChangeStatus(criteria);</pre>
+
+ <p>
+ Criteria object specifies the message whose status to change and the new status.
+ The <code>ChangeStatus</code> method returns an object that contains an error code and an error message.
+ </p>
+
+
+
+
+
+ Criteria object specifies the message whose status to change and the new status. The ChangeStatus method returns an object that contains an error code and an error message.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <p>
+ The <code>Delete</code> method deletes a message.
+ This is a synchronous method.
+ </p>
+
+ <pre>result = so.IMessaging.Delete(criteria);</pre>
+
+ <p>
+ The criteria object has <code>messageId</code> attribute that specifies the message to delete.
+ The <code>Delete</code> method returns an object that contains an error code and an error message.
+ </p>
+
+
+
+
+
+ The criteria object has messageId attribute that specifies the message to delete.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <p>The SystemInfo Service API allows widgets to access and modify system information on a device.</p>
+ <p>The API is integrated into WRT through the <code>device</code> object.</p>
+ <p>To use the SystemInfo Service API, your widget must first create a service object for it using the <code>device.getServiceObject()</code> method.</p>
+ <p>Use <code>Service.SysInfo</code> to identify the service provider and <code>ISysInfo</code> to identify the supported interface:</p>
+ <pre>var so = device.getServiceObject("Service.SysInfo", "ISysInfo");</pre>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The <code>GetInfo</code> method retrieves information about a system attribute.
+ This method can be called both synchronously and asynchronously.
+
+
+
+
+
+ This is an object that specifies the search criteria.
+
+
+
+
+
+ The callback argument is the name of the method that is executed when an asynchronous Send call has status information to return. You must define this method separately.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The <code>SetInfo</code> method modifies the value of a system attribute.
+ This is a synchronous method.
+
+
+
+
+
+ This is an object that specifies the new value for the system attribute.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The <code>GetNotification</code> method notifies the client when the value of a system attribute is changed.
+ This is an asynchronous method.
+
+
+
+
+
+ This is an object that specifies the system attribute to monitor for changes.
+
+
+
+
+
+ The callback argument is the name of the method that is executed when a GetNotification call has results or status information to return.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The <code>Cancel</code> method cancels an ongoing asynchronous call made with a SystemInfo Service API method.
+ This is a synchronous method.
+
+
+
+
+
+ This is an object with the TransactionID property (number). criteria.TransactionID specifies the transaction ID of the asynchronous call to cancel. The transaction ID is the result.TransactionID value that was returned as part of the result of the initial call.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <p>The Location Service API allows widgets to retrieve information about the physical location of a device and to perform calculations based on location information.</p>
+ <p>The API is integrated into WRT through the <code>device</code> object.</p>
+
+ <p>To use the Location Service API, your widget must first create a service object for it using the <code>device.getServiceObject()</code> method.</p>
+ <p>Use <code>Service.Location</code> to identify the service provider and <code>ILocation</code> to identify the supported interface:</p>
+
+ <pre>var so = device.getServiceObject("Service.Location", "ILocation");</pre>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <p>
+ The <code>GetLocation</code> method retrieves the current location of the device.
+ This method can be called both synchronously and asynchronously.
+ </p>
+
+ <p>
+ For synchronous calls:
+ </p>
+ <pre>result = so.ILocation.GetLocation(criteria);</pre>
+
+ <p>
+ For asynchronous calls:
+ </p>
+ <pre>result = so.ILocation.GetLocation(criteria, callback);</pre>
+
+ <p>
+ If synchronous, the <code>GetLocation</code> method returns an object that contains the requested location information, an error code, and an error message.
+ If asynchronous, the <code>GetLocation</code> method returns an object that contains the initial return value for the asynchronous call it started.
+ The actual location information is returned by the callback method in the ReturnValue property of its result object.
+ The availability of specific location information depends on the underlying GPS technology.
+ Other factors, such as the number of satellites available for a location fix, also affect what information can be returned.
+ You can change the positioning system used by an S60 device from the Settings > General > Positioning > Positioning methods menu.
+ It takes time to retrieve the initial position fix. Subsequent requests are faster.
+ This criteria object specifies what type of device location information is returned and how.
+ The callback argument is the name of the method that is executed when an asynchronous GetLocation call has results or status information to return.
+ You must define this method separately.
+ This argument is used only with an asynchronous <code>GetLocation</code> call.
+ For more information about the criteria and returned object properties and how to define them refer to WDL Help documentation.
+ </p>
+
+
+
+
+
+ This is an object that specifies what type of device location information is returned and how.
+
+
+
+
+ The callback argument is the name of the method that is executed when an asynchronous GetLocation call has results or status information to return. You must define this method separately. This argument is used only with an asynchronous GetLocation call.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <p>
+ The <code>Trace</code> method retrieves periodic updates about the current location of the device based on a predefined update interval.
+ This is an asynchronous method.
+ </p>
+
+ <pre>result = so.ILocation.Trace(criteria, callback);</pre>
+
+ <p>
+ The <code>Trace</code> method returns an object that contains the initial return value for the asynchronous call it started.
+ The actual location information is returned by the callback method in the ReturnValue property of its result object.
+ </p>
+
+ <p>
+ <code>Trace</code> retrieves location updates until cancelled with <code>CancelNotification</code>.
+ You can therefore have only one <code>Trace</code> call (one instance) pending or in use at any given time.
+ The availability of specific location information depends on the underlying GPS technology.
+ Other factors, such as the number of satellites available for a location fix, also affect what information can be returned.
+ You can change the positioning system used by an S60 device from the Settings > General > Positioning > Positioning methods menu.
+ It takes time to retrieve the initial position fix. Subsequent requests are faster.
+ The criteria object specifies what type of device location information is returned and how. Note that these input properties are similar to what the GetLocation method uses.
+ The callback argument is the name of the method that is executed when Trace has results or status information to return. You must define this method separately.
+ For more information about the criteria and returned object properties and how to define them refer to WDL Help documentation.
+ </p>
+
+
+
+
+
+ This is an object that specifies what type of device location information is returned and how. Note that these input properties are similar to what the GetLocation method uses.
+
+
+
+ The callback argument is the name of the method that is executed when Trace has results or status information to return. You must define this method separately.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <p>
+ The <code>Calculate</code> method performs mathematical calculations based on a source location and a target location.
+ This is a synchronous method.
+ </p>
+
+ <pre>result = so.ILocation.Calculate(criteria);</pre>
+
+ <p>
+ The <code>Calculate</code> method returns an object that contains the calculation results, an error code, and an error message.
+ The criteria object specifies the mathematical operation to perform and the input values to use in the operation.
+ For more information about the criteria and returned object properties and how to define them refer to WDL Help documentation.
+ </p>
+
+
+
+
+
+ This is an object that specifies the mathematical operation to perform and the input values to use in the operation.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <p>
+ The <code>CancelNotification</code> method cancels an outstanding asynchronous call.
+ This is a synchronous method.
+ </p>
+
+ <pre>result = so.ILocation.CancelNotification(criteria);</pre>
+
+ <p>
+ The criteria object specifies whether to cancel a GetLocation call or a Trace call.
+ The object must contain the <code>CancelRequestType</code> property (string) that is used to specify the type of call to cancel.
+ </p>
+
+ <p>
+ The possible values for <code>criteria.CancelRequestType</code> are:
+ <ul>
+ <li><code>GetLocCancel</code> cancels an asynchronous <code>GetLocation</code> call.</li>
+ <li><code>TraceCancel</code> cancels a <code>Trace</code> call.</li>
+ </ul>
+ </p>
+
+ <p>
+ The <code>CancelNotification</code> method returns an object that contains an error code and an error message.
+ For more information about the criteria and returned object properties and how to define them refer to WDL Help documentation.
+ </p>
+
+
+
+
+
+ This is an object that specifies whether to cancel a GetLocation call or a Trace call. The object must contain the CancelRequestType property (string) that is used to specify the type of call to cancel. The possible values for criteria.CancelRequestType are: "GetLocCancel" cancels an asynchronous GetLocation call. "TraceCancel" cancels a Trace call.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <p>
+ The Sensor Service API allows widgets to access data provided by the physical sensors of a device.
+ </p>
+ <p>
+ The data from a given sensor is mapped to one or more sensor channels, which the API can listen to.
+ The available sensors depend on the device.
+ </p>
+ <p>
+ The API is integrated into WRT through the <code>device</code> object.
+ </p>
+ <p>
+ To use the Sensor Service API, your widget must first create a service object for it using the <code>device.getServiceObject()</code> method.
+ </p>
+ <p>
+ Use <code>Service.Sensor</code> to identify the service provider and <code>ISensor</code> to identify the supported interface:
+ </p>
+
+ <pre>so = device.getServiceObject("Service.Sensor", "ISensor");</pre>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <p>
+ The <code>FindSensorChannel</code> method searches for sensor channels available on the device.
+ This is a synchronous method.
+ </p>
+
+ <pre>result = so.ISensor.FindSensorChannel(criteria);</pre>
+
+ <p>
+ The criteria object specifies the search criteria.
+ The <code>FindSensorChannel</code> method returns an object that contains the requested sensor channel information, an error code, and an error message.
+ </p>
+
+
+
+
+
+ This is an object that specifies the search criteria.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <p>
+ The <code>RegisterForNotification</code> method registers the client to receive data from one sensor channel.
+ This is an asynchronous method.
+ </p>
+
+ <pre>result = so.ISensor.RegisterForNotification(criteria, callback);</pre>
+
+ <p>
+ The <code>RegisterForNotification</code> method returns an object that contains the initial return value for the asynchronous call it started.
+ The actual sensor data is returned by the callback method in the ReturnValue property of its result object.
+ </p>
+
+
+
+
+
+ This is an object that specifies the sensor channel to listen for data.
+
+
+
+
+ The callback argument is the name of the method that is executed when a RegisterForNotification call has results or status information to return. You must define this method separately.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <p>
+ The <code>Cancel</code> method stops an ongoing <code>RegisterForNotification</code> call.
+ This is a synchronous method.
+ </p>
+
+ <pre>result = so.ISensor.Cancel(criteria);</pre>
+
+ <p>
+ The criteria object has the <code>TransactionID</code> property which specifies the transaction ID of the <code>RegisterForNotification</code> call to cancel.
+ The transaction ID is the value that was returned as part of the result of the initial call.
+ The <code>Cancel</code> method returns an object that contains an error code and an error message.
+ </p>
+
+
+
+
+
+ This is an object with the TransactionID property (number). criteria.TransactionID specifies the transaction ID of the RegisterForNotification call to cancel. The transaction ID is the result.TransactionID value that was returned as part of the result of the initial call.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <p>
+ The <code>GetChannelProperty</code> method retrieves information about a sensor channel property.
+ This is a synchronous method.
+ </p>
+
+ <pre>result = so.ISensor.GetChannelProperty(criteria);</pre>
+
+ <p>
+ This is an object that specifies which sensor channel property to retrieve information about.
+ The <code>GetChannelProperty</code> method returns an object that contains the requested channel property information, an error code, and an error message.
+ </p>
+
+
+
+
+
+
+ This is an object that specifies which sensor channel property to retrieve information about.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Service Object
+
+
+
+
+
+
+
+
+ Service Object
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This Service API allows widgets to:
+ <p>
+ <ul>
+ <li>access, create, and manage calendars/calendar entries,</li>
+ <li>access and manage information about contacts,</li>
+ <li>access and manage information about landmarks and landmark categories,</li>
+ <li>add, read, and delete logging events such as call logs, messaging logs, and so forth,</li>
+ <li>retrieve information (metadata) about the media files stored in the Media Gallery of a device.</li>
+ </ul>
+ </p>
+ <p>
+ To use the <code>IDataSource</code> Service API, your widget must first create a service object for it using the <code>device.getServiceObject()</code> method.
+ </p>
+ <p>
+ Use <code>Service.Calendar</code> or <code>Service.Contact</code> or <code>Service.Landmarks</code> or <code>Service.Logging</code> or <code>Service.MediaManagement</code> to identify the service provider and <code>IDataSource</code> to identify the supported interface:
+ </p>
+
+ <pre>var so = device.getServiceObject("Service.Calendar", "IDataSource");</pre>
+
+
+
+
+
+
+
+
+ <p>The AppManager Service API allows widgets to access and launch applications on a mobile device.</p>
+ <p>The API is integrated with WRT through the <code>device</code> object.</p>
+ <p>To use the AppManager Service API, your widget must first create a service object for it using the <code>device.getServiceObject()</code> method.</p>
+ <p>Use <code>Service.AppManager</code> to identify the service provider and <code>IAppManager</code> to identify the supported interface:</p>
+
+ <pre>var so = device.getServiceObject("Service.AppManager", "IAppManager");</pre>
+
+
+
+
+
+
+
+
+ <p>The Messaging Service API allows widgets to send, retrieve, and manage messages using the Messaging Center of a device.</p>
+ <p>The API is integrated into WRT through the <code>device</code> object.</p>
+
+ <p>To use the Messaging Service API, your widget must first createa service object for it using the <code>device.getServiceObject()</code> method.</p>
+ <p>Use <code>Service.Messaging</code> to identify the service provider and <code>IMessaging</code> to identify the supported interface:</p>
+
+ <pre>var so = device.getServiceObject("Service.Messaging", "IMessaging");</pre>
+
+
+
+
+
+
+
+
+
+ <p>The SystemInfo Service API allows widgets to access and modify system information on a device.</p>
+ <p>The API is integrated into WRT through the <code>device</code> object.</p>
+ <p>To use the SystemInfo Service API, your widget must first create a service object for it using the <code>device.getServiceObject()</code> method.</p>
+ <p>Use <code>Service.SysInfo</code> to identify the service provider and <code>ISysInfo</code> to identify the supported interface:</p>
+ <pre>var so = device.getServiceObject("Service.SysInfo", "ISysInfo");</pre>
+
+
+
+
+
+
+
+
+ <p>The Location Service API allows widgets to retrieve information about the physical location of a device and to perform calculations based on location information.</p>
+ <p>The API is integrated into WRT through the <code>device</code> object.</p>
+
+ <p>To use the Location Service API, your widget must first create a service object for it using the <code>device.getServiceObject()</code> method.</p>
+ <p>Use <code>Service.Location</code> to identify the service provider and <code>ILocation</code> to identify the supported interface:</p>
+
+ <pre>var so = device.getServiceObject("Service.Location", "ILocation");</pre>
+
+
+
+
+
+
+
+
+
+ <p>The Sensor Service API allows widgets to access data provided by the physical sensors of a device.</p>
+ <p>The data from a given sensor is mapped to one or more sensor channels, which the API can listen to.
+ The available sensors depend on the device.</p>
+ <p>The API is integrated into WRT through the <code>device</code> object.</p>
+ <p>To use the Sensor Service API, your widget must first create a service object for it using the <code>device.getServiceObject()</code> method.</p>
+ <p>Use <code>Service.Sensor</code> to identify the service provider and <code>ISensor</code> to identify the supported interface:</p>
+
+ <pre>so = device.getServiceObject("Service.Sensor", "ISensor");</pre>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The <code>device</code> object is a built-in JavaScript object in the widget engine.
+ It was introduced in WRT 1.1 to allow widgets access to S60 Platform Services through Service APIs.
+ The <code>device</code> object is used to create service objects for specific Service APIs.
+ These service objects can then be used to access the services made available through the Service APIs.
+
+
+
+
+
+
+
+
+
+
+ The <code>device</code> object is a built-in JavaScript object in the widget engine.
+ It was introduced in WRT 1.1 to allow widgets access to S60 Platform Services through Service APIs.
+ The <code>device</code> object is used to create service objects for specific Service APIs.
+ These service objects can then be used to access the services made available through the Service APIs.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The <code>getServiceObject</code> method creates an object that is used to access the services made available through a Service API.
+ This object is referred to as a <b>service object</b>.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This is a text string that defines the service provider name, that is, the name of the type of service object to create.
+ Possible values : "Service.AppManager",
+ "Service.SysInfo",
+ "Service.Sensor",
+ "Service.Messaging",
+ "Service.MediaManagement",
+ "Service.Logging",
+ "Service.Location",
+ "Service.Calendar",
+ "Service.Contact"
+
+
+
+
+
+
+ This is a text string that defines the supported interface for the specified service provider.
+ Possible values : "IAppManager",
+ "ISysInfo",
+ "ISensor",
+ "IMessaging",
+ "IDataSource",
+ "ILocation"
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <p>
+ The following example creates a service object for the Media Management Service API:
+ </p>
+
+ <pre>var so = device.getServiceObject("Service.MediaManagement", "IDataSource");</pre>
+
+
+
+
+
+
+
+
+