API Reference

Complete API documentation for all functions, procedures, and types in the GitHub Contributions Chart application

Overview

This page documents all public functions, procedures, and types used in the GitHub Contributions Chart application. All code references include file locations for easy navigation.

Functions

DownloadWeb

Downloads content from a URL using HTTP GET request.

Location: Unit1.pas:55-64

function DownloadWeb(aURL: string): string;

aURL · string · required

The URL to download from. Must be a valid HTTP or HTTPS URL.

Returns: string - The response body as a string

Description:

Creates a temporary TNetHTTPClient instance, performs a GET request to the specified URL, and returns the response content as a string. The HTTP client is automatically freed after the request completes.

Implementation:

function DownloadWeb(aURL: string): string;
var httpClient: TNetHTTPClient;
begin
  httpClient := TNetHTTPClient.Create(nil);
  try
    Result := httpClient.Get(aURL).ContentAsString;
  finally
    httpClient.Free;
  end;
end;

Example Usage:

var
  htmlContent: string;
begin
  htmlContent := DownloadWeb('https://api.example.com/data');
end;

This function is blocking and will freeze the UI during the request. Consider using asynchronous methods for production applications.

---

GetGitHubContributions

Fetches GitHub contribution data for a specific user from the github-contributions API.

Location: Unit1.pas:66-72

function GetGitHubContributions(username: string): TJSONObject;

username · string · required

The GitHub username to fetch contributions for. Case-sensitive.

Returns: TJSONObject - A JSON object containing contribution data with the following structure:

{
  "years": ["2024", "2023", "2022"],
  "contributions": [
    {
      "date": "2024-03-04",
      "count": 5,
      "intensity": 2
    },
    ...
  ]
}

Description:

Calls the github-contributions.vercel.app API to retrieve contribution data for the specified username. The response is parsed into a TJSONObject for easy traversal.

Implementation:

function GetGitHubContributions(username: string): TJSONObject;
var
  response: string;
begin
  response := DownloadWeb(Format('https://github-contributions.vercel.app/api/v1/%s', [username]));
  Result := TJSONObject.ParseJSONValue(TEncoding.ASCII.GetBytes(response), 0) as TJSONObject;
end;

Example Usage:

var
  data: TJSONObject;
  years: TJSONArray;
begin
  data := GetGitHubContributions('sallar');
  if data.TryGetValue<TJSONArray>('years', years) then
  begin
    // Process years array
  end;
end;

The caller is responsible for freeing the returned TJSONObject to prevent memory leaks.

---

FormatMark

Formats a date into a human-readable string with ordinal suffix (e.g., “March 4th”).

Location: Unit1.pas:109-120

function FormatMark(ADate: TDateTime): string;

ADate · TDateTime · required

The date to format. Must be a valid TDateTime value.

Returns: string - Formatted date string with ordinal suffix

Description:

Converts a date into a readable format like “January 1st”, “February 2nd”, “March 3rd”, or “April 4th”. Uses invariant format settings to ensure consistent English month names.

Implementation:

function FormatMark(ADate: TDateTime): string;
begin
  Result := Format('%s %d', [TFormatSettings.Invariant.LongMonthNames[MonthOf(ADate)], DayOf(ADate)]);

  case DayOf(ADate) of
    1, 21, 31: Result := Result + 'st';
    2, 22: Result := Result + 'nd';
    3, 23: Result := Result + 'rd';
    else
       Result := Result + 'th';
  end;
end;

Example Output:

• FormatMark(EncodeDate(2024, 3, 1)) → “March 1st”
• FormatMark(EncodeDate(2024, 3, 2)) → “March 2nd”
• FormatMark(EncodeDate(2024, 3, 3)) → “March 3rd”
• FormatMark(EncodeDate(2024, 3, 4)) → “March 4th”
• FormatMark(EncodeDate(2024, 3, 21)) → “March 21st”

This function is used to generate tooltip text for each contribution square in the chart.

---

IntensityThemeColor

Maps a GitHub intensity level (0-4) to the corresponding color in the current theme.

Location: Unit1.pas:175-178

function IntensityThemeColor(AIntensity: Integer): TColor;

AIntensity · Integer · required

The contribution intensity level. Valid range: 0-4

• 0: No contributions
• 1: Low contributions
• 2: Medium contributions
• 3: High contributions
• 4: Very high contributions

Returns: TColor - The color corresponding to the intensity level in the active theme

Description:

Looks up the color for a given intensity level from the currentTheme.Grades array. This function provides the color mapping that makes the contribution graph visually represent activity levels.

Implementation:

function IntensityThemeColor(AIntensity: Integer): TColor;
begin
  Result := currentTheme.Grades[AIntensity];
end;

Example Colors (StandardTheme):

• Intensity 0: $F0EDEB (Very light gray)
• Intensity 1: $A8E99B (Light green)
• Intensity 2: $63C440 (Medium green)
• Intensity 3: $4EA130 (Dark green)
• Intensity 4: $396E21 (Very dark green)

Passing an intensity value outside the 0-4 range will cause an array index out of bounds exception.

---

Procedures

CustomWeekDayOfTheYear

Calculates the week number and day of week for a given date, with support for different week start days.

Location: Unit1.pas:122-143

procedure CustomWeekDayOfTheYear(
  ADate: TDateTime; 
  AFirstDayOfWeek: Integer; 
  var AWeek, ADay: Integer
);

ADate · TDateTime · required

The date to calculate week and day for.

AFirstDayOfWeek · Integer · required

Specifies which day starts the week:

• 0: Sunday as first day of week
• 1: Monday as first day of week

AWeek · Integer · required

Output parameter. Receives the week number of the year (1-53).

Special values:

• -1: Date belongs to previous year’s last week
• WeeksInYear + 1: Date belongs to next year’s first week

ADay · Integer · required

Output parameter. Receives the day of the week (1-7).

When AFirstDayOfWeek = 0 (Sunday start):

• 1 = Sunday, 2 = Monday, …, 7 = Saturday

When AFirstDayOfWeek = 1 (Monday start):

• 1 = Monday, 2 = Tuesday, …, 7 = Sunday

Description:

Calculates both the ISO week number and day of the week, accounting for edge cases where dates fall in the previous or next year’s weeks. Supports both Sunday-first and Monday-first week conventions.

Implementation:

procedure CustomWeekDayOfTheYear(ADate: TDateTime; AFirstDayOfWeek: Integer; var AWeek, ADay: Integer);
var
  tmpYear: Word;
begin
  AWeek := WeekOfTheYear(ADate, tmpYear);
  if tmpYear < YearOf(ADate) then
    AWeek := -1
  else if tmpYear > YearOf(ADate) then
    AWeek := WeeksInYear(ADate) + 1;

  ADay := DayOfTheWeek(ADate);

  if (AFirstDayOfWeek = 1) then
  begin
    ADay := (ADay mod 7) + 1;

    if DayOfTheWeek(ADate) = 7 then
    begin
      Inc(AWeek);
    end;
  end;
end;

Example Usage:

var
  weekNum, dayNum: Integer;
  myDate: TDateTime;
begin
  myDate := EncodeDate(2024, 1, 1);  // January 1st, 2024 (Monday)
  
  // Monday as first day
  CustomWeekDayOfTheYear(myDate, 1, weekNum, dayNum);
  // weekNum = 1, dayNum = 1 (Monday)
  
  // Sunday as first day
  CustomWeekDayOfTheYear(myDate, 0, weekNum, dayNum);
  // weekNum = 1, dayNum = 2 (Monday is 2nd day when Sunday is first)
end;

This function is critical for positioning contribution squares correctly in the chart grid.

---

Types

TTheme

Defines a complete color scheme for the application.

Location: Themes.pas:8-13

type
  TTheme = record
    Background: TColor;
    Text: TColor;
    Meta: TColor;
    Grades: array [0..4] of TColor;
  end;

Fields:

Background · TColor

The background color for the form and controls.

Text · TColor

The primary text color for labels and annotations.

Meta · TColor

The secondary text color for metadata (currently unused).

Grades · array [0..4] of TColor

An array of 5 colors representing contribution intensity levels:

• Grades[0]: No contributions (lightest)
• Grades[1]: Low contributions
• Grades[2]: Medium contributions
• Grades[3]: High contributions
• Grades[4]: Very high contributions (darkest/most saturated)

Description:

A record type that encapsulates all colors needed for the application’s visual theme. The Grades array provides the five-level color scale used to visualize GitHub contribution intensity.

---

Constants

StandardTheme

The default light theme matching GitHub’s standard color scheme.

Location: Themes.pas:16-21

const
  StandardTheme: TTheme = (
    Background: $FFFFFF;  // White
    Text: $000000;        // Black
    Meta: $666666;        // Gray
    Grades: ($F0EDEB, $A8E99B, $63C440, $4EA130, $396E21);
  );

Color Breakdown:

Background

$FFFFFF - Pure white

Text

$000000 - Pure black

Meta

$666666 - Medium gray

Grade 0

$F0EDEB - Very light beige (no activity)

Grade 1

$A8E99B - Light green

Grade 2

$63C440 - Medium green

Grade 3

$4EA130 - Dark green

Grade 4

$396E21 - Very dark green

Delphi uses BGR color format, so $RRGGBB in CSS becomes $BBGGRR in Pascal.

---

GithubDarkTheme

The dark theme matching GitHub’s dark mode color scheme.

Location: Themes.pas:23-28

const
  GithubDarkTheme: TTheme = (
    Background: $101217;  // Very dark gray (almost black)
    Text: $FFFFFF;        // White
    Meta: $DDDDDD;        // Light gray
    Grades: ($221B16, $203800, $2D6000, $3D9810, $45D527);
  );

Color Breakdown:

Background

$101217 - Very dark gray (near black)

Text

$FFFFFF - Pure white

Meta

$DDDDDD - Light gray

Grade 0

$221B16 - Dark brown (no activity)

Grade 1

$203800 - Very dark green

Grade 2

$2D6000 - Dark green

Grade 3

$3D9810 - Medium bright green

Grade 4

$45D527 - Bright lime green

---

Module-Level Variables

These variables maintain global state for the application.

Location: Unit1.pas:49-53

var
  gitHubContributions: TJSONObject;
  monthTitles: TArray<TAnnotationTool>;
  dayTitles: TArray<TAnnotationTool>;
  currentTheme: TTheme;

gitHubContributions

gitHubContributions · TJSONObject

Stores the complete JSON response from the GitHub contributions API. Contains both the years array and the contributions array. This object persists across chart redraws to avoid re-fetching data.

monthTitles

monthTitles · TArray<TAnnotationTool>

Array of 12 annotation tools, one for each month label (Jan, Feb, Mar, etc.). Created in FormCreate and positioned in DrawChart.

dayTitles

dayTitles · TArray<TAnnotationTool>

Array of 3 annotation tools for alternating weekday labels (Mon, Wed, Fri or Sun, Tue, Thu depending on week start). Created in FormCreate and positioned in DrawChart.

currentTheme

currentTheme · TTheme

The currently active theme. Initialized to StandardTheme in the unit’s initialization section. Modified by the theme toggle button.

The gitHubContributions object should be freed before the application exits to prevent memory leaks. Consider adding cleanup code to the form’s OnDestroy event.

---

Usage Examples

Fetching and Displaying Contributions

var
  contributions: TJSONObject;
  years: TJSONArray;
  contribArray: TJSONArray;
begin
  // Fetch data
  contributions := GetGitHubContributions('octocat');
  
  try
    // Extract years
    if contributions.TryGetValue<TJSONArray>('years', years) then
      ShowMessage('Available years: ' + years.Count.ToString);
    
    // Extract contributions
    if contributions.TryGetValue<TJSONArray>('contributions', contribArray) then
      ShowMessage('Total contributions: ' + contribArray.Count.ToString);
  finally
    contributions.Free;
  end;
end;

Custom Theme Creation

var
  customTheme: TTheme;
begin
  customTheme.Background := clWhite;
  customTheme.Text := clBlack;
  customTheme.Meta := clGray;
  
  // Create a red-scale gradient
  customTheme.Grades[0] := RGB(255, 240, 240);
  customTheme.Grades[1] := RGB(255, 200, 200);
  customTheme.Grades[2] := RGB(255, 150, 150);
  customTheme.Grades[3] := RGB(200, 50, 50);
  customTheme.Grades[4] := RGB(150, 0, 0);
  
  currentTheme := customTheme;
end;

Date Formatting

var
  dateStr: string;
  today: TDateTime;
begin
  today := Now;
  dateStr := FormatMark(today);
  // Output: "March 4th" (for March 4, 2026)
  
  Chart1.Title.Text.Add(dateStr);
end;

---

See Also

Code Structure

Learn how these APIs are used in the application architecture

Development Setup

Set up your environment to use these APIs