VS:OpenURL

.VectorScript|VectorScript ..VS:Function Reference|Function Reference ..VS:Function_Reference_Appendix|Appendix

Description

Opens a web page or file using the default browser or appropriate application (e.g. Adobe Acrobat). Returns a boolean indicating the success of the operation.

The URL (Uniform Resource Locator) is a pointer to a resource on the World Wide Web. It specifies both the protocol and location of the document to open.

• For files on the local computer, the URL should begin with file:// protocol specifier.
• For web pages, the URL should begin with http://. The URL should use forward slashes / to separate parts of the path.

There are some platform differences to be aware of. Windows will accept either or / as the path separators. MacOS X requires that file:// URLs begin with /Volumes/ before the drive name. Also, currently the MacOS X implementation of OpenURL does not accept spaces in the URL. Spaces should be replaced with the escape code Note #20, see after the code block. before calling this function.

Note: The function VS:GetFolderPath returns a string with separators specific for the platform it is running on (/ on Mac and on Windows). If your script calls this function to assemble a local file:// URL then you will have to replace the : separators with / characters.

FUNCTION OpenURL(
         URLname   :DYNARRAY[] of CHAR) : BOOLEAN;

def vs.OpenURL(URLname):
    return BOOLEAN

Parameters

URLname

DYNARRAY[] of CHAR

The Uniform Resource Locator for the web page or file to open.

Remarks

PROCEDURE Main;
VAR
  dialogID :INTEGER;
  boo      :BOOLEAN;

  PROCEDURE Dialog_Setup;
  BEGIN
    dialogID := CreateLayout('Sample Dialog', FALSE, '', '');
    CreateControl     (dialogID, 4, 3, '', 25);
    CreatePushButton  (dialogID, 1, 'OK');
    CreatePushButton  (dialogID, 2, 'Cancel');
    CreatePushButton  (dialogID, 3, 'Help');

    SetFirstLayoutItem(dialogID,4);
    SetBelowItem      (dialogID,4,1,0,0);
    SetRightItem      (dialogID,1,2,0,0);
    SetRightItem      (dialogID,2,3,0,0);
  END;

  PROCEDURE Dialog_Handler(VAR item :LONGINT; data :LONGINT);
  BEGIN
    CASE item OF 
      3: boo := OpenURL(Concat(GetFolderPath(1), 'VWHelpHelpLinks.pdf'));
    END;
  END;

BEGIN
  Dialog_Setup;
  IF RunLayoutDialog(dialogID, Dialog_Handler) = 1 then BEGIN
    AlrtDialog('OK');
  END;
END;
RUN(Main);

1.) Use forward slash / to separate directories. (Windows accepts or / as separators. )

2.) Use file:/// to begin the URL if it is a file on your local machine.

theURL := 'file:///C:/Documents and Settings/Jeff/My Documents/Test.htm';

3.) Use http:// to begin the URL if the page is hosted by a web server.

theURL := 'http://www.vectordepot.com';

4.) Tests show that this can also be used with mailto:. Could be a nice way to get feedback from your users...

If you are on MacOS X:

5.) For a file on the boot drive, the path should not contain the name of the drive.

theURL := 'file:///Documents/Test.html';

6.) For file on other non-boot drive or partition, the path should begin with /Volumes/ followed by the name of the partition.

theURL := 'file:///Volumes/Xtra2/SomeTest.html';

7.) Spaces are not allowed in the url. Replace them with %20 characters. This is a bug that we should be able to fix in future version. (MacOS 9 and Windows seem to accept spaces.)

theURL := 'file:///Documents/This%20Is%20A%20Test.html';

{--------------------------------------------------------------------}
{ A sample script from Jeff }
{ }
{ This sample VectorScript opens the VectorScript Function Reference }
{ in a web browser.  It gets the full path to the application, }
{ appends it to the partial path for the help file.  The paths are }
{ tweaked so that they will be accepted by the OpenURL call. }
{ Tested on MacOS X 10.3.3, MacOS 9.2.2 and Windows XP with VW 11.}

PROCEDURE OpenURLExample;
VAR
boo :BOOLEAN;
theURL, finalURL : STRING;


{-------------------------}
function RunningOnMacPlatform: BOOLEAN;
var
  appMajor, appMinor, appIncr, platform : INTEGER;

begin
  GetVersion(appMajor, appMinor, appIncr, platform);
  if (platform = 1) then
    RunningOnMacPlatform := true
  else
    RunningOnMacPlatform := false;
end;


{-------------------------}
function RunningOnMacOSX: BOOLEAN;
VAR
  major, minor, incr : LONGINT;
begin
  GetOSVersion(major, minor, incr);
  if (RunningOnMacPlatform = true) and ((major = 0) or (major = 10)) then
    RunningOnMacOSX := true
  else
    RunningOnMacOSX := false;
end;


{-------------------------}
procedure EscapeSpacesURL(theURL :String; VAR destURL : STRING);
var
  spaceIndex : INTEGER;
  locURL : DYNArray[] of CHAR;

begin
  { Replace space characters with %20 }
  locURL := theURL;
  spaceIndex := Pos(' ', locURL);
  while (spaceIndex <> 0) do begin
    locURL[spaceIndex] := '%';
    Insert('20', locURL, spaceIndex + 1);
    spaceIndex := Pos(' ', locURL);
  end;

  destURL := locURL;
end;


{-------------------------}
function GetFolderURL(whichFolder : INTEGER) : STRING;
{ Calls GetFolderPath and then converts path to valid URL string for
each platform. }
var
  appDir : DYNARRAY[] of CHAR;
  sepIndex : INTEGER;
begin
  { Get Path }
  appDir := GetFolderPath(whichFolder);

  { If Mac, replace : with / }
  if (RunningOnMacPlatform = true) then begin
    sepIndex := Pos(':', appDir);
    while (sepIndex <> 0) do begin
      appDir[sepIndex] := '/';
      sepIndex := Pos(':', appDir);
    end;
  end;

  { If MacOS X, prepend /Volumes/ }
  if (RunningOnMacOSX = true) then
    appDir := ConCat('/Volumes/', appDir)   { MacOS X }
  else
    appDir := ConCat('/', appDir);                  { MacOS 9 and Windows }

  { Prepend the file:// specifier }
  appDir := ConCat('file://', appDir);

  GetFolderURL := appDir
end;

{-------------------------}
BEGIN
  theURL := Concat(GetFolderURL(1), 'VWHelp/VectorScript
  Reference/VSFunctionReference.html');

  { Escape the space characters }
  EscapeSpacesURL(theURL, finalURL);

  boo := OpenURL(finalURL);       { OpenURL is actually limited to 256 characters. }
  message(finalURL, ' RESULT IS ', boo);

END;
RUN(OpenURLExample);

Example

VectorScript

{ Open a webpage. }
status := OpenURL('http://www.vectorworks.net');

{ Open an HTML file on MacOS X. }
status := OpenURL('file:///Volumes/MyMacXHD/Documents/My%20Files/Test.html');

{ Open a PDF file in Acrobat on MacOS X. }
status := OpenURL('file:///Volumes/MyMacXHD/Documents/My%20Files/VSLG11.pdf');

{ Open a PDF file in Acrobat on MacOS 9. }
status := OpenURL('file:///MyMac9HD/My Files/VSLG11.pdf');

{ Open a PDF file in Acrobat on Windows. }
status := OpenURL('file:///C:/My Files/VSLG11.pdf';

Version

Availability: from VectorWorks10.0