// I am not a smiley – <:~:>

Der Prozedur-Editor hält ein kleines Feature bereit, das für die Dokumentation von Prozeduren sehr sinnvoll ist. Dieses Feature möchte ich heute vorstellen.

Verlinkte Dokumentation

Angenommen Sie entwickeln gerade eine Funktion, die Breite, Höhe und Farbtiefe einer Windows-Bitmap-Datei ausliest. Diese könnte dann wie folgt aussehen:

// ******************************************************************
// *  ReadBitmapInfo - Breite, Höhe und Farbtiefe eines BMP lesen   *
// ******************************************************************
sub ReadBitmapInfo
(
  aFileName   : alpha;
  var aSize   : point;
  var aBpp    : int
)
: logic;
  local
  {
    tHdl         : handle;
    tFileHeader  : byte[14];
    tBmpInfoSize : long;
    tBmpWidth    : long;
    tBmpHeight   : long;
    tBmpPlanes   : word;
    tBmpBitCount : word;
    tHaveBitmap  : logic;
  }
{
  // Datei öffnen
  tHdl # FsiOpen(aFileName,_FsiStdRead);
  if (tHdl > 0)
  {
    // Bitmap File Header + Bitmap Info Header lesen
    if ((tHdl->FsiRead(tFileHeader) = 14) and
        (tHdl->FsiRead(tBmpInfoSize) = 4) and
        (tHdl->FsiRead(tBmpWidth) = 4) and
        (tHdl->FsiRead(tBmpHeight) = 4) and
        (tHdl->FsiRead(tBmpPlanes) = 2) and
        (tHdl->FsiRead(tBmpBitCount) = 2))
    {
      // Dateikennung 'BM' verifizieren
      if (StrChar(tFileHeader[1]) = 'B'  and
          StrChar(tFileHeader[2]) = 'M')
      {
        // Gültige Windows Bitmap-Datei
        tHaveBitmap # true;
        aSize       # PointMake(tBmpWidth,tBmpHeight);
        aBpp        # tBmpBitCount;
      }
    }
    tHdl->FsiClose();
  }
  return(tHaveBitmap);
}

Die Routine liest zuerst den sogenannten ‘File Header’ der Bitmap-Datei. Anschließend wird der ‘Info Header’ ausgelesen. Dieser enthält die gewünschten Informationen.
Soll die Routine nun erweitert werden, damit diese weitere Informationen zurückliefern kann, kommt man in der Regel nicht drum her rum einen Blick in die Microsoft-Dokumentation zu werfen. Aber wo war die noch mal zu finden? Klar im Internet, aber wo genau?

Google Ade!

Eine Dokumentation des Bitmap-Formates ist unter dem folgenden Link vorhanden:
http://msdn.microsoft.com/en-us/library/dd183391.aspx

Fügen Sie den Link nun eingeschlossen in die Zeichenfolge <: :> in den Kommentar-Block ein:

// ****************************************************************
// *  ReadBitmapInfo - Breite, Höhe und Farbtiefe eines BMP lesen *
// *  <: http://msdn.microsoft.com/en-us/library/dd183391.aspx :> *
// ****************************************************************

Wenn Sie jetzt mit der linken Maustaste bei gehaltener Strg-Taste einen Doppelklick auf den Link durchführen, wird die Seite im Browser geöffnet. Dadurch haben Sie die passende Internet-Seite immer parat.

Anweisungen

Voraussetzung für die Erkennung einer Anweisung, die mit <: :> angeklickt werden kann, ist das sie in einem Kommentar enthalten ist. Dieser muss zudem mit ‘//’ beginnen. Die Anweisung kann sich nicht über mehrere Zeilen erstrecken. Es können jedoch beliebig viele solcher Anweisungen erstellt werden – an beliebigen Stellen innerhalb der Prozedur.
Die Anweisungen sind nicht auf Web-Links beschränkt. Sie können jedes Kommando angeben, dass von der Windows-Shell gestartet werden kann. Die folgenden Beispiele verdeutlichen das.

// Kommandozeile aufrufen - <: cmd.exe :>
// Control-Panel aufrufen - <: control.exe :>
// Datei in Word öffnen   - <: c:\mydocument.doc :>

Relative Pfade können auch verwendet werden:

// Beschreibung zur Datenbank - <: ~\notes\readme.txt :>

Die Tilde gibt an, dass die Datei ‘readme.txt’ im Verzeichnis der Datenbank im Unterverzeichnis ‘notes’ zu finden ist.
Vielleicht können Sie nun auch erahnen, was es mit dem Titel dieses Blog-Artikels auf sich hat. Sie ahnen es bereits: auch hierbei handelt es sich um eine Anweisung…