Алгоритмы

Для начала решим, как мы будем действовать. Когда-то давно я искал хорошую реализацию градиентной заливки, но у них у всех был большой недостаток - громоздкость и нечитабельность алгоритма. Кроме того, было только два вида - горизонтальная и вертикальная заливка. В моей статье вид заливки ограничится лишь вашей фантазией. Я создал библиотеку градиентных функций и забыл об этой проблеме. Позже я приобрел библиотеку RX и увидел там почти аналогичную реализацию, но опять таки только 2-3 вида заливки. ДАЕШЬ ТВОРЧЕСКУЮ РЕАЛИЗАЦИЮ!

Итак, начнем с того, что чтобы не быть зависимым от вида заливки, нужно цвета держать в массиве. Единожды заполнив массив плавным переходом цветов, его можно использовать для разных видов заливки. Кроме того, используя массив гораздо легче будет сделать множественную заливку - скажем, от синего к красному, потом от красного к зеленому и от зеленого к синему. Давайте рассмотрим алгоритм заполнения массива.

Сразу оговоримся о типе TColorArray.

type TColorArray = array of TColor; procedure SimpleFillArray(FromColor, ToColor: TColor; var ColorArray: TColorArray; ArrayWidth: Integer); var i: Integer; R1,G1,B1, R2,G2,B2: Byte; begin R1 := GetRValue(ColorToRGB(FromColor)); G1 := GetGValue(ColorToRGB(FromColor)); B1 := GetBValue(ColorToRGB(FromColor)); R2 := GetRValue(ColorToRGB(ToColor)); G2 := GetGValue(ColorToRGB(ToColor)); B2 := GetBValue(ColorToRGB(ToColor)); for i := 0 to ArrayWidth do ColorArray[i] := RGB(R1 - i*(R1 - R2) div ArrayWidth, G1 - i*(G1 - G2) div ArrayWidth, B1 - i*(B1 - B2) div ArrayWidth); end;

Объясним все по порядку. Для начала, нам нужно извлечь отдельные RGB-координаты из цветов FromColor, ToColor. Делается это с помощью функций GetXValue(X=R,G,B). Однако, это не единственный способ получения RGB-координат. Не забудем, что цвет - это обычное целочисленное число. Поэтому, координаты можно достать и так:

R := Color mod $100; G := Color div $100 mod $100; B := Color div $10000;

и так:

R := Color and $FF; G := (Color and $FF00) shr 8; B := (Color and $FF0000) shr 16;

и так:

R := Lo(Color); G := Lo(Color shr 8); B := Lo((Color shr 8) shr 8);

Что вы выберете - ваше дело. Мне удобнее через GetXValue.

Итак, координаты извлечены, затем, согласно алгоритму, заполняются ячейки массива. (х - расстояние от начала массива, в цикле это счетчик i).

В этой процедуре мы заполняем массив простым переходом цветов. Но можно сделать и круче - переход с несколькими цветами, заданными массивом:

procedure ComplexFillArray(Colors: array of TColor; var ColorArray: TColorArray; ArrayWidth: Integer); var ColArray: TColorArray; i,j,Temp: Integer; Equal: Boolean; begin //Вначале проверим число цветов //Если массив пуст: if High(Colors) < 0 then begin raise Exception.Create('Specify at least one color!'); Exit; end; //Если только один элемент, то //просто заполняем массив этим цветом: if High(Colors) = 0 then begin for i := 0 to ArrayWidth do ColorArray[i] := Colors[0]; Exit; end; //ширина одной полосы, необходимой для перехода от //одного цвета массива к другому. Естественно, ширина //кратна числу цветов в массиве. Temp := ArrayWidth div (High(Colors)); SetLength(ColArray, Temp + 1);

Equal := (ArrayWidth mod Temp)=0; //булевая переменная //- наличие остатка после деления - сигнализирует о том, //укладываются ли полосы в массив полностью, или нет for i := 0 to High(Colors) - 1 do begin SimpleFillArray(Colors[i], Colors[i + 1], ColArray, Temp); for j := 0 to Temp do ColorArray[j + i*Temp] := ColArray[j]; end; //если имеет место неполное заполнение, то делаем следующее: //отступаем от конца на расстояние ArrayWidth //mod Temp и закрашиваем от //цвета на этом расстоянии до последнего цвета (см. рисунок )

Теперь мы можем заполнять массив несколькими цветами. Теперь что касается входного параметра ArrayWidth (длина массива). Как определить, какая длина массива нам нужна? Давайте посмотрим на примере функции горизонтальной заливки. Посмотрим, сколько нам нужно в этом случае. Для горизонтальной заливки длина массива соответствует количеству пикселей, размещенных по высоте заливаемой области:

function HorizontalArrayWidth(FillRect: TRect): Integer; begin Result := abs(FillRect.Bottom - FillRect.Top); end;

Теперь, зная длину, можно и заливать. Мой принцип - лучше медленно в начале, но быстро потом, чем наоборот. Всегда рисуйте на временном битмапе, а потом отображайте этот битмап на канву. Тем более это касается сложных нелинейных видов заливки (рассмотрим позже).

procedure HorizontalGradient(Canvas: TCanvas; FillRect: TRect; Colors: TColorArray); var i: Integer; TempBmp: TBitmap; begin TempBmp := TBitmap.Create; TempBmp.Width := abs(FillRect.Right - FillRect.Left); TempBmp.Height := abs(FillRect.Bottom - FillRect.Top); try With TempBmp do for i := 0 to TempBmp.Height do begin Canvas.Pen.Color := Colors[i]; Canvas.MoveTo( - 1, i); Canvas.LineTo(TempBmp.Width + 1, i); end; Canvas.StretchDraw(FillRect, TempBmp); finally TempBmp.Free; end; end;

Пример использования:

procedure TForm1.HorizontalClick(Sender: TObject); var ColArr:TColorArray; begin SetLength(ColArr, HorizontalArrayWidth(BMP.Canvas.ClipRect) + 1); // не забудем, что индексация // идет от нуля ComplexFillArray([clBlack,clRed, $004080FF, clYellow,clGreen,clBlue, clNavy, clPurple, clBlack], ColArr, HorizontalArrayWidth(BMP.Canvas.ClipRect)); HorizontalGradient(BMP.Canvas, BMP.Canvas.ClipRect, ColArr); Canvas.StretchDraw(Clientrect,BMP); Finalize(ColArr); end;

Я разделил процесс создания - заполнения массива цветами с процессом градиентной заливки потому, что этот массив может повторно использоваться, но в принципе, процесс создания - заполнения можно занести внутрь процедуры заливки в случае единичного использования массива.

По поводу объекта BMP - это глобальный битмап, который я создаю в FormCreate, чтобы не создавать каждый раз временный битмап и форма не мерцала при каждой отрисовке. Полностью демо можно будет скачать.

Аналогично выглядит функция вертикальной заливки. Длина массива соответствует ширине заливаемой области:

function VerticalArrayWidth(FillRect: TRect): Integer; begin Result := abs(FillRect.Right - FillRect.Left); end; procedure VerticalGradient(Canvas: TCanvas; FillRect: TRect; Colors: TColorArray); var i: Integer; TempBmp: TBitmap; begin TempBmp := TBitmap.Create; TempBmp.Width := abs(FillRect.Right - FillRect.Left); TempBmp.Height := abs(FillRect.Bottom - FillRect.Top); try With TempBmp do for i := 0 to TempBmp.Width do begin Canvas.Pen.Color := Colors[i]; Canvas.MoveTo(i, - 1); Canvas.LineTo(i, TempBmp.Height); end; Canvas.StretchDraw(FillRect, TempBmp); finally TempBmp.Free; end; end;

До этого, мы рассматривали лишь простые варианты заливки. Теперь перейдем, собственно, к творчеству. Давайте посмотрим, как можно сделать что-нибудь другое. Например, диагональную заливку с левого верхнего к правому нижнему углу. Все, что нужно сделать - это заполнить массив и рисовать линии по диагонали. Длина массива должна быть равна сумме высоты и ширины заполняемой области. Почему? Давайте посмотрим. Процедура заполнения должна выполниться в два приема - вначале закрашиваем левый верхний треугольник, то есть спускаемся по левой стороне области, продолжая линии до верхней стороны области. По достижении нижнего левого угла направление закрашивания меняется. Теперь идем по нижней стороне, продолжая линии до правой стороны (при условии квадратной области), если же область неквадратная, то часть линий будет касаться верхней стороны. Проблема с неквадратностью может быть решена, если создать временный квадратный битмап, стороны которого равны максимальной стороне прямоугольной области. Затем этот битмап закрасить и растянуть на закрашиваемую область с помощью метода StretchDraw (или стандартной функции из модуля Windows - StretchBlt). Аналогично будет проходить закрашивание по диагонали из правого верхнего в левый нижний угол, изменится лишь направление закрашивания.

Что еще? Да хоть килограмм! Давайте посмотрим заливку "веером". Смысл веера в том, что все линии проводятся из одного угла на стороны, противоположные ему. Длина массива здесь та же, что и в случае диагонально заливки.

Теперь посмотрим круговые виды: полуокружности сверху-снизу, слева-справа, заливка концентрическими окружностями от краев к центру.

В случаях полуокружностей длина массива под цвета должна быть равна половине ширины (в случае слева-справа) и половине высоты (в случае сверху-снизу). В случае с концентрическими окружностями - половине минимальной стороны заливаемой области, т.к. радиус окружности (или дуги) изменяется от нуля до центра заливаемой области. Надо сказать, что предварительно нужно залить область начальным цветом, чтобы была иллюзия того, что переход действительно плавен.

function LeftRightPiesArrayWidth(FillRect: TRect): Integer; begin Result := VerticalArrayWidth(FillRect) div 2; end; function TopBottomPiesArrayWidth(FillRect: TRect): Integer; begin Result := HorizontalArrayWidth(FillRect) div 2; end; function CirclesArrayWidth(FillRect: TRect): Integer; var Width, Height, minus: Integer; begin Width := abs(FillRect.Right - FillRect.Left); Height := abs(FillRect.Bottom - FillRect.Top); minus := 15*(Width + Height) div Min(Width, Height); //величина minus определена чисто эмпирически, //возможно вы найдете лучше Result := Min(Width, Height) div 2+minus; end; procedure TopBottomPiesGradient(Canvas: TCanvas; FillRect: TRect; Colors: TColorArray); var i: Integer; TempBmp: TBitmap; begin TempBmp := TBitmap.Create; TempBmp.Width := abs(FillRect.Right - FillRect.Left); TempBmp.Height := abs(FillRect.Bottom - FillRect.Top); try With TempBmp do begin Canvas.Brush.Color := Colors[0]; Canvas.FillRect(FillRect); for i := 0 to TempBmp.Height div 2 do begin Canvas.Pen.Color := Colors[i]; Canvas.Brush.Color := Colors[i]; Canvas.Pie(0, - (TempBmp.Height div 2), TempBmp.Width, (TempBmp.Height div 2) - i, 0, 0, TempBmp.Width, 0); Canvas.Pie(0, (TempBmp.Height div 2)+i, TempBmp.Width, 3*(TempBmp.Height div 2), 0, 0, 0, 0); end; end; Canvas.StretchDraw(FillRect,TempBmp); finally TempBmp.Free; end; end; procedure LeftRightPiesGradient(Canvas: TCanvas; FillRect: TRect; Colors: TColorArray); var i: Integer; TempBmp: TBitmap; begin TempBmp := TBitmap.Create; TempBmp.Width := abs(FillRect.Right - FillRect.Left); TempBmp.Height := abs(FillRect.Bottom - FillRect.Top); try With TempBmp do begin Canvas.Brush.Color := Colors[0]; Canvas.FillRect(FillRect); for i := 0 to TempBmp.Width div 2 do begin Canvas.Pen.Color := Colors[i]; Canvas.Brush.Color := Colors[i]; Canvas.Pie(- TempBmp.Width div 2, 0, (TempBmp.Width div 2) - i, TempBmp.Height, 0, TempBmp.Height, 0, 0); Canvas.Pie((TempBmp.Width div 2) + i, 0, 3*TempBmp.Width div 2, TempBmp.Height, TempBmp.Width, 0, TempBmp.Width, TempBmp.Height); end; end; Canvas.StretchDraw(FillRect, TempBmp); finally TempBmp.Free; end; end; procedure CirclesGradient(Canvas: TCanvas; FillRect: TRect; Colors: TColorArray); var i,Minus: Integer; TempBmp:TBitmap; begin TempBmp := TBitmap.Create; TempBmp.Width := abs(FillRect.Right - FillRect.Left); TempBmp.Height := abs(FillRect.Bottom - FillRect.Top); Minus := 15*(TempBmp.Width + TempBmp.Height) div Min(TempBmp.Width, TempBmp.Height); try With TempBmp do begin Canvas.Brush.Color := Colors[0]; Canvas.FillRect(FillRect); for i := 0 to CirclesArrayWidth(FillRect) do begin Canvas.Pen.Color := Colors[i]; Canvas.Brush.Color := Colors[i]; Canvas.Ellipse(Rect(i - Minus, i - Minus, TempBmp.Width - i + Minus, TempBmp.Height - i + Minus)); end; end; Canvas.StretchDraw(FillRect, TempBmp); finally TempBmp.Free; end; end;

Давайте теперь посмотрим заливку "конверт". Суть ее в том, что область закрашивается сходящимися в центр прямоугольниками. Длина массива здесь, также, должна быть равна половине минимальной стороны заливаемой области. Это нужно для того, чтобы был действительно эффект конверта. Кстати, мой любимый вид заливки :)

function EnvelopeArrayWidth(FillRect: TRect): Integer; var Width, Height: Integer; begin Width := abs(FillRect.Right - FillRect.Left); Height := abs(FillRect.Bottom - FillRect.Top); Result := Min(Width,Height) div 2; end; procedure EnvelopeGradient(Canvas: TCanvas; FillRect: TRect; Colors: TColorArray); var i: Integer; TempBmp: TBitmap; begin TempBmp := TBitmap.Create; TempBmp.Width := abs(FillRect.Right - FillRect.Left); TempBmp.Height := abs(FillRect.Bottom - FillRect.Top); try With TempBmp do for i := 0 to EnvelopeArrayWidth(FillRect) do begin Canvas.Brush.Color := Colors[i]; Canvas.FillRect(Rect(i, i, TempBmp.Width - i, TempBmp.Height - i)); end; Canvas.StretchDraw(FillRect, TempBmp); finally TempBmp.Free; end; end;

Ну, не будем раздувать и без того большую статью... Быстренько пробежимся по другим видам, которые я реализовал в своем модуле.

Заливка волнами. Длина массива - ширина (в случае горизонтальных волн) или высота (в случае вертикальных волн) заливаемой области. Кстати, частоту также можно задать. Но формула подобрана также эмпирически. Кстати, волны реализованы очень легко - заливаете битмап-полоску и потом в цикле рисуете градиентные полоски на i-ом расстоянии, равном синусу: Round(50*sin(Frequency*i). (Frequency - частота синусоиды).

Заливка звездой. Длина массива - чисто эмпирически подобрано - 2/3 минимальной из сторон. Ну, это сделано, чтобы звезда была побольше. В принципе, 2/3 можете убрать. Для построения звезды достаточно вспомнить геометрию;)

Заливка ромбом. Длина массива - такая же, что и в случае заливки конвертом.

Предела фантазии нет - все зависит только от вас. Можно комбинировать из уже имеющихся или придумать что-то новое. Мне после 16ти видов просто надоело... Надеюсь, статья не показалась вам скучной и подтолкнула на творческие поиски:)).

Немного теории.

Все цвета в двоичном коде представляются в виде трехбайтовых (или более) последовательностей. Есть различные схемы представления цвета - RGB, HLS, CMYK и некоторые другие, (например OpenGL) которые используются исключительно в системах компьютерной графики, нас они не очень интересуют. Итак, все по порядку. RGB (Red, Green, Blue) представляет цвет следующим образом: это трех байтовая последовательность вида $GGBBRR. Каждый байт представляет определенный оттенок (от 0 до 255) цветов: красный, зеленый, синий. Например, $FF0000 означает чистый синий цвет полной интенсивности, $00FF00 - чистый зеленый, $0000FF - чистый красный, $FFFFFF - черный цвет, $000000 - белый. Таким образом, задав определенное числовое значение, можно добиться того или иного оттенка искомого цвета. Но это в формате RGB. Чаще всего в Делфи мы пользуемся типом TColor, в котором добавлен еще 1 байт -указатель на замену цвета. Этот байт может принимать три различных значения - ноль ($00), единицу ($01) или двойку ($02). Что это значит:

Видимо, всегда лучше устанавливать значение первого байта равным нулю ($00), по крайней мере, так происходит при получении типа TColor при помощи функции RGB.

Схемой RGB пользоваться удобнее и привычнее, чем остальные, но расскажем немного и о них. Схема HLS(Hue, Light, Saturation) - Оттенок, Яркость, Насыщенность. Как видно из аббревиатуры, цвет представляется несколько иначе - через оттенок определенного цвета, его яркость и насыщенность. К сожалению, никогда этой схемой не пользовался, поэтому пример привести не могу:(. CMYK - Cyan-Magenta-Yellow-blacK палитра (голубой-сиреневый-желтый-черный), используется в издательских системах как более четко передающая цвета, чем палитра RGB. Также ничего не могу сказать, кроме того, что уже сказано. В моей статье мы будем рассматривать только модель RGB.

Теперь, что же такое градиент? Градиент - это плавный переход от одного цвета к другому. Очень хорошо градиент можно показать на примере радуги.

Допустим, вам нужно получить промежуточный цвет между красным и синим. Для этого просто находим среднее арифметическое отдельных координат RGB.

(255, 0, 0) + (0, 0, 255) = ((255+0)div 2, (0+0)div 2, (0+255)div 2) = (127, 0, 127).

То есть получили сиреневый цвет. Для случая многих цветов нужно будет сложить координаты всех цветов и разделить на их количество. Как же можно сделать этот плавный переход? Итак, пусть заданы 2 цвета своими координатами ((A1, A2, A3) и (B1, B2, B3)) и линия (длиной h пикселов), по которой нужно залить.

Тогда каждый цвет каждого пиксела, находящегося на расстоянии x пикселов от начала будет равен

Теперь, наконец, перейдем, собственно, к реализации градиентной заливки.

Вступление.

Частенько приходится задумываться над тем, на сколько скуден стандартный интерфейс, насколько он безжизненнен (я не говорю про ХР - там все меняется к лучшему, но и там есть ляпы). Хочется сделать что-нибудь эдакое, грандиозное, чтобы глаз радовался. Представляю на ваш суд один из инструментов, который позволит скрасить серые будни программиста. Статья не претендует на фундаментальность - это просто зарисовка, эскиз к вашим будущим работам. Итак, начнем.

Добавление картинок и гиперссылок.

Обычное дело - указать адрес своего сайта и/или электронной почты в разделе "Поддержка". Как сделать, чтобы эта ссылка выглядела и функционировала как гиперссылка на Веб-страницах? Аналог гиперссылки, т.е. тега anchor (<a>) HTML в WinHelp - "hotspot". Hotspot - это область, по щелчку мыши на которой, выполняется какое-либо действие из предусмотренных в WinHelp. В данном случае нам нужно запустить один из макросов WinHelp, а именно макрос ExecFile. Этот макрос напоминает функцию WinApi ShellExecute. Синтаксис его такой:

Первый параметр, как написано в справке, может указывать на программу или файл. Однако, как и в ShellExecute, вместо имени файла можно указать URL, например "http://www.mysite.ru" или "mailto:nekto@somemail.ru".
Чтобы создать hotspot, запускающий такой макрос, нужно сделать следующее:
Сразу после текста hotspot'a ввести символ "!", а сразу за ним - текст макроса, например:

Примечание: URL в скобках должен быть без кавычек.
Далее, нужно отформатировать этот отрывок так: текст hotspot'a должен иметь двойное подчеркивание, а символ "!" и текст макроса после него - иметь атрибут "скрытый". И то, и другое делается через меню "Формат" -> "Шрифт" (см. рис. 2) На всякий случай, еще раз уточню: двойное подчеркивание (выпадающий список рядом с "цветом текста"), а не зачеркивание..

Теперь, если добавить такой hotspot и компилировать проект, то мы увидим в своей справке, что в строке текста

Наш сайт: www.mysite.ru - адрес выглядит и функционирует как гиперссылка.

Общие сведения

В состав справки к программе обычно входит несколько файлов:

Пишем простой хелп

Справочная система (далее в тексте также - "справка") - важная составная часть любой более-менее сложной (и даже простой) программы. Существуют разные форматы справочных систем. Справка в формате WinHelp - о ней в статье и пойдет речь, Html-help - как, например, справка к ОС Windows или к программам MS Office. В качестве справки может выступать набор связанных html-файлов, например так организована справка к СУБД MySQL. Из достоинств WinHelp можно назвать ее надежность и меньшие, чем у HTML-help, требования к ресурсам. Существуют различные программы для создания справочных систем названных типов. Однако, для создания несложной справки вполне достаточно стандартной программы MS Help Workshop, которая поставляется с Delphi. Потребуется еще редактор rtf файлов, в данной статье описывается работа со знакомым всем MS Word'ом. Все действия, которые будут описаны - несложные, но мне в свое время потребовалось определенное количество усилий и времени, чтобы разобраться по справке к Help Workshop, как все это делать. Надеюсь, что статья сможет облегчить этот путь для других. Расчитана она на начинающих. В статье описывается создание простой справки, оглавления к ней, создание последовательностей просмотра, вставка рисунков и гиперссылок, а также подключение справки к программе. Рассматривается только техническая сторона, вопрос о том, что написано в справке, оставлен в стороне.

Присоединяем справку к программе.

Чтобы из меню в программе вызвать оглавление справки, нужно воспользоваться функцией

Один из способов вызова справки - нажатие клавиши F1. Можно организовать вызов контекстной справки при нажатии на F1, когда активным является тот или иной элемент управления. Для этого соответствующей теме справки нужно присвоить номер, а затем этот номер присвоить свойству HelpContext элемента управления. Чтобы задать номера для тем справки, нужно открыть проект справки в HelpWorkshop и нажать кнопку "Map" в правой части окна. Нажимаем в диалоговом окне "Add", вводим идентификатор темы и произвольный номер (например, 1 :) ), повторяем это для всех нужных тем (каждой - свой номер), закрываем окно и нажимаем в очередной раз "Save and Compile". Затем в Delphi, в окне инспектора объектов, присваиваем нужные номера нужным элементам управления (напоминаю, свойство HelpContext).

Создание оглавления справки.

Теперь создаем собственно оглавление. Оно состоит из элементов двух типов - разделы справки, которые включают в себя несколько тем и представлены в оглавлении справки значком книжки и сами темы - текст и картинки, представлены в оглавлении справки значком листа со знаком вопроса на нем (можно посмотреть это в оглавлении любой справки). Также в оглавление можно вставить макросы и включить файлы (include), этого я здесь касаться не буду. Справа на панели есть набор кнопок для добавления и манипуляции элементами оглавления. (Add Below - Добавить ниже, Add Above - Добавить выше, Move Right - Сдвинуть вправо, Move Left - Сдвинуть влево, Edit, Delete). При помощи них создаем нужную структуру оглавления. При добавлении раздела в диалоговом окне нужно указать только его название, при добавлении темы - название, идентификатор (тот, который мы задали ей в rtf-файле, когда вставляли концевую сноску), имя help-файла и имя окна. Если тема находится в том же help-файле, который мы указали как главный, то имя help-файла указывать не нужно. Имя окна указывать тоже не обязательно, если оно не указано, то тема откроется в окне по-умолчанию. Нужно сохранить файл оглавления (он будет иметь расширение .cnt) в той же директории, где находится help-файл лучше с тем же именем, что и help-файл. Теперь нужно снова открыть файл проекта .hpj и, нажав кнопку "Options", в открывшемся диалоговом окне на закладке "Files" указать наш файл оглавления (Contents file). Закрываем диалоговое окно, снова нажимаем "Save and Compile". Теперь при двойном щелчке мышью по значку файла справки должно открыться ее оглавление, из которого можно получить доступ ко всем темам.

Мне не удалось, похоже, это невозможно, создать такую структуру оглавления, чтобы в самом левом ряду сначала шел значок темы (например, "Общие сведения"), а под ним - значки разделов. Пришлось даже для одиночной темы создавать раздел, содержащий ее одну.

Создание последовательностей просмотра.

Разметка имеет следующий вид: это тоже концевые сноски, как и для идентификаторов тем, однако в данном случае знаком сноски служит не символ "#", а "+" - знак плюса. Текстом сносок может быть либо число, либо строка символов. Просмотр будет осуществляться в порядке возрастания (как при сортировке строк). Отсюда следующее - если используются номера, то нужно вставлять необходимое количество нулей перед значащими цифрами для правильной сортировки. Например, если у Вас 20 тем, то первые нужно нумеровать как 01, 02, и т.д. Возможно несколько вариантов:

Чтобы добавить кнопки навигации "<<" и ">>" в окне справки (по умолчанию их нет), нужно определить хотя бы одно окно. Для этого, открыв файл проекта в HelpWorkshop, нужно нажать кнопку "Windows..." в правой части окна. В диалоговом окне с закладками нажать кнопку "Add..." и в открывшемся окне ввести в поле названия "main", а поле типа окна очистить, после чего нажать OK. Теперь у нас определено одно окно, различные свойства которого можно изменять, перемещаясь по закладкам. На закладке "Buttons" отмечаем галочкой "Browse". Нажимаем ОК, готово. Теперь окно справки будет иметь нужные кнопки. Нажимаем "Save and Compile" внизу окна и можем проверять, что получилось в выходном help файле.

Создание тематических файлов.

Обычно справка содержит несколько тем и оглавление, из которого можно перейти к этим темам. Самый простой вариант: если тема - одна и оглавления нет. В таком случае просто пишем то, что нужно и сохраняем это в файле с расширением ".rtf". Для создания нескольких тем процесс усложняется ненамного:

Для того, чтобы тема были доступна из оглавления к справке, нужно задать ей идентификатор. Для этого нужно в то место текста, куда будет впоследствии происходить переход из оглавления (начало темы или, если нужно, другое место), вставить специальную разметку, а именно: концевую сноску. Символом сноски нужно выбрать "#". Идентификатором темы служит текст сноски. Например, создадим тему "Поддержка", отделим ее от других тем разрывами страниц и зададим ей идентификатор "support". Для этого поместим каретку ввода около заголовка темы и выберем в меню "Вставка"->"Сноска...". В диалоговом окне (рис.1) выбираем вид сноски - "концевая", нумерация - "другая", в окошке для ввода символа пишем "#" (без кавычек, понятное дело). Нажимаем ОК, ссылка добавлена и каретка автоматически переведена к тексту ссылки. Пишем "support". Готово.
Повторяем то же самое для всех тем справки. Сохраняем файл. Теперь можно попробовать создать свой хелп.

Запускаем программу HelpWorkshop. Это - файл Hcw.exe в директории Delphi\Help\Tools\. Создаем новый проект через меню "File"->"New"->"Help Project". Справа на панели есть ряд кнопок, нажимаем "Files...". В диалоговом окне добавляем наш тематический файл и закрываем это окно. Сохраним проект - это будет файл с расширением hpj (Help Project). Насколько я понял, после первого запуска Help Workshop связывает себя с файлами hpj, а также - с файлами оглавления справки (cnt), так что их потом можно открывать двойным щелчком мышью. Для создания help-файла можно просто нажать кнопку "Save and Compile". Откроется новое окно с сообщением о результате компиляции. Предположим, что все в порядке, закроем это окно. Теперь в директории, где находился наш проект (.hpj), должен появиться файл справки. Однако, при двойном щелчке мышью на нем мы сможем просмотреть только первую тему. Чтобы просматривать все темы и перемещаться между ними, нужно добавить файл оглавления.

Безобидные(?) Hints

Ниже приведен код простой функции, которая не содержит синтаксических ошибок, но при её компиляции будет получено три Hint'а (в коде они отмечены красным). Давайте разберем их подробно.

Итак, получается, что Hint'ы обращают наше внимание на странности и несуразицы в коде с точки зрения "правильного" компилятора. Конечно, приведенный пример очень прост и надуман и может не убедить вас, но если в коде функции, которая содержит не один десяток операторов, появляется hint, стоит обратить на него внимание, поверьте.

Рассмотренные выше ситуации можно и нужно исправлять. Но бывают случаи, когда нет возможности исправить код так, чтобы не получать Hint's при компиляции. Рассмотрим небольшой пример по созданию собственных классов:

Допустим, что в этом случае все не так просто, как это видится компилятору и функция FutureTools, например, нигде не используется вовсе не потому, что вы о ней забыли или она никому не нужна. Возможно это задел на будущее. Можно, конечно, закомментировать и объявление функции и код ее реализации до поры до времени. Но можно сделать и иначе, несколько изящнее.

Возможно, что по условию конкретной задачи понижение видимости метода в классе TLists оправдано, а корректировать код базового класса нет возможности, тогда придется попросить компилятор не принимать во внимание эту ситуацию.

Как раз для таких случаев предусмотрена сцециальная дирректива компилятора: {$HINTS OFF}. Она отключает проверку кода на предмет обнаружения Hint'ов до тех пор, пока в коде не встретится обратная дирректива — {$HINTS ON}. Если в обрамленном этими специальными комментариями коде и будут "опасные" Hint-ситуации, они будут игнорироваться компилятором.

Воспользовавшись этими диррективами, мы получим код, который компилируется не только без ошибок, но и без Hint'ов:

Примечание:
Не поддавайтесь искушению раз и навсегда "заткнуть" с помощью {$HINTS OFF} упрямый компилятор, пользы от этого вам, как программисту, не будет никакой...

Hints and Warnings, или Спасение утопающих

Елена Филиппова, Королевство Дельфи
15 апреля 2003г.

Каждая программа содержит по крайней мере одну ошибку
Народная мудрость

Никогда не делает ошибок тот, кто просто ничего не делает. Это тоже народная мудрость. Поэтому с ошибками в коде сталкивается в своей работе каждый программист. После того, как программа успешно откомпилирована, преодолен первый этап борьбы. :о)

Не секрет, что гораздо сложнее бороться с ошибками, возникающими во время выполнения программы, особенно, когда они приводят не просто к ее "падению", а к неадекватной работе, наслаивая проблемы и создавая "наведенные" ошибки. И здесь уже надежды на компилятор нет... Спасение утопающих, как известно, дело рук этих самых утопающих.

Материал данной статьи не имеет отношения к теме тестирования и отладки. Он предназначен начинающим программистам, дабы обратить их внимание на "соломинку", которую протягивает утопающим IDE Delphi в нелегком деле борьбы с ошибками :о) Ведь не зря же ее называют дружественной средой разработки.

Хочу сразу обратить ваше внимание на то, что все приводимые примеры не являются реальными, они специально упрощены и только иллюстрируют объяснение материала.

Коварные Warnings

Предупреждения-warnings обладают гораздо более высоким уровнем опасности с точки зрения компилятора. История с абстрактным классом служит тому примером. Разберем еще несколько случаев возникновения warning'ов: Return value of function 'VarCompare' might be undefined Значение результата функции 'VarCompare' может быть неопределено.

Казалось бы, с точки зрения логики в тексте функции все верно. Перекрыты все возможные случаи и сообщение компилятора выглядит несколько неуместно. Но не стоит ждать от него слишком много, компилятор не может (да и не обязан) вникать в логику программы. Для того, чтобы избавиться от этого сообщения, было бы правильно переписать это код. Например, вот так:

В итоге и компилятор "отстанет", и код будет более читабельным. Это сообщение только на первый взгляд кажется безобидным, ниже приведен пример, в котором возникает аналогичное предупреждение и содержится реальная ошибка — если возникнет исключительная ситуация при открытии файла, результат функции, действительно, не будет определен. В итоге это скажется при выполнении программы, когда ошибки никто не будет ожидать.

Совершенно справедливое замечание. Если во время работы программы в функцию будет передана пустая строка, нам обеспечен знаменитый Access violation.
Вернемся еще раз к примеру с определением собственных классов.

Точно также, как и в случае с hint'ами, существуют опции для отключения сообщений компилятора о предупреждениях — {$WARNINGS OFF}, и для их включения — {$WARNINGS ON}. И точно так же хочу обратить внимание на нежелательность использования этих опций без нужды. Молчание компилятора в этом случае не будет означать отсутствие проблемы :о)

О пользе сообщений компилятора

В каждом уважающем себя форуме есть список вопросов, признанных как off-topic. Часть из них сто раз уже разжевана, часть решается нажатием клавиши F1 и так далее. На каждом форуме борятся с ними по-своему, но, к огромному сожалению, задающих такие вопросы не становится меньше. Более того, вопрошающие частенько еще и обижаются, когда их отсылают :о) Вот пример классического off-topic'а:

В ответ на такой вопрос, господа, как правило, начинают страшно ругаться. :о) Самые вежливые слова, которые получает автор вопроса, звучат примерно так — "Сколько же можно?! Хелп когда научитесь читать?!" На что автор, как ему кажется, абсолютно справедливо, начинает огрызаться, что типа, откуда ему было знать, что такое абстрактный метод и что на этом самом TStrings не написано, какие у него методы!
Проведем маленький эксперимент и напишем такой код:

При компиляции нам будет выдан warning, как раз на той строке, где создается экземпляр класса — Constructing instance of 'TStrings' containing abstract methods. Я надеюсь, что текст этого предупреждения абсолютно ясен и не требует пояснений...

Смотрите, что получается, ошибок компиляции нет, человек с высоко поднятой головой игнорирует "всю эту ерунду" и просто не обращает внимания на предупреждения компилятора! В итоге, он получает ошибку времени выполнения, некоторое личное недоумение, кучу словесных тычков и подзатыльников на форуме. А ведь его предупреждали! :о)

IDE Delphi, как дружественная среда программирования, кроме обычного факта уведомления о сообщениях компилятора, предоставляет дополнительные возможности — если дважды кликнуть на тексте сообщения (рис. 2), то курсор автоматически переместиться на ту строку в редакторе кода, в которой, по мнению компилятора, возникает спорная ситуация. Если же на тексте сообщения (hint или warning) нажать F1, то откроется окно справочной системы (рис. 3) по конкретному hint'у или warning'у. Там будет описано, в каких случаях компилятор выдает такое сообщение и что Delphi вообще "думает" по этому поводу.

Цель этого материала, не рассказать

Типы сообщений компилятора

Информацию о результате компиляции и сборки программы можно увидеть в окне, показывающем процесс компиляции (рис. 1), и на панели сообщений, встроенной в редактор кода (рис. 2).

рис. 1 Сообщения компилятора бывают трех типов. В этом списке они приведены по убыванию степени опасности, если так можно выразиться :о) Error — ошибка Warning - предупреждение Hint - подсказка или совет.

Довольно распространенное отношение начинающих программистов к этим сообщениям заключается в полном игнорировании предупреждений и советов. Ведь не ошибки же? Программа откомпилирована и запускается на исполнение. И, может быть, даже работает :о)

Мне приходилось встречать на некоторых форумах "дружеские советы" новичкам, сводившиеся к предложению "не обращать на эту ерунду внимания, это оптимизатор у Delphi выделывается."
Так ли это на самом деле?

При наличии в проекте ошибок-Errors, не будет сформирован исполняемый файл и, волей не волей, ошибки придется исправлять. Наличие же сообщений Hints и Warnings позволяет запускать приложение. Обратите внимание на окно процесса компиляции (рис. 1), в строке "Done" написано не Compiled, что, в общем-то, ожидалось, а предупреждение There are warnings. Несмотря на отсутствие ошибок, проект откомпилирован с тремя "подсказками" и пятью "предупреждениями".
Насколько безопасно не обращать на это внимание? Начнем с самых безобидных сообщений компилятора, с его советов — Hints.

Иконки в трейбаре? Проще чем кажется!

Во многих форумах с завидной систематичностью выплывают вопросы об иконках в трее и многие программеры с недовольством отвечают: "Это же так просто, почитай документацию". Да, действительно просто - но лучше все посмотреть на практике, в человеческом, так сказать, изложении. Эта статья как раз и предназначена для заполнения некоторого "информационного вакуума" сложившегося по данной теме и расскажет о некоторых приемах работы с треем в Delphi.

Описание параметров:

Определения

Итак, tray - это область рабочего стола Explorer'а, которая находится в одном из углов экрана, "там где часы". Вся информация, которую можно "почерпнуть" из трея, представлена в виде возможно изменяющихся иконок, отражающих состояние программы, и всплывающих подсказок. К числу активных действий над иконкой в трее можно отнести щелчок левой кнопкой и вызов контекстного меню правой.

Параметр - тип

CbSize - DWORD
Wnd - HWND
UID - UINT
UFlags - UINT
UCallbackMessage - UINT
Icon - HICON
SzTip - Array [0..64] of AnsiChar

С чего начать

Для операций с иконками трея используется только одна функция Windows - Shell_NotifyIconData, определение которой "звучит" следующим образом:

function Shell_NotifyIcon (dwMessage: DWORD; lpData: PNotifyIconData): BOOL; stdcall;

И в качестве параметров функция воспринимает: dwMessage - идентификатор сообщения, которое посылается иконке в трее. Может принимать значения NIM_ADD,NIM_DELETE,NIM_MODIFY; lpData - указатель на структуру TNotifyIconData, в которой помещена информация о параметрах иконки; возвращаемое значение - принимает true при успешном завершении операции или false в противном случае.

Как видно, сам синтаксис функции не сказал нам ничего нового о том, как реализована работа с треем. Эта функция только изменяет состояние иконки в зависимости от значения параметра dwMessage - а это значит, что вся нужная нам информация находится в структуре TNotifyIconData. Давайте теперь рассмотрим ее более детально…

Tray в чистом виде

А теперь приступим к собственно выводу иконки в трей. Для начала создадим форму, где все это разместим:

type
TForm1 = class (TForm)
Button1: TButton;
procedure Button1Click (Sender: TObject);
procedure FormDestroy (Sender: TObject);
private
procedure TrayDefaultHandler (var Message:TMessage);
{Private declarations}
public
Data:TNotifyIconData;
{Public declarations}
end;

procedure TForm1.Button1Click (Sender: TObject);
var H:THandle;
begin
H:=AllocateHWnd (TrayHandler);
FillChar (S,SizeOf (S),#0);
Data.cbSize:=SizeOf (S);
Data.Wnd:=H;
Data.uCallbackMessage:=WM_TRAYICON;
Data.uFlags:=NIF_ICON or NIF_TIP or NIF_MESSAGE;
Data.hIcon:=Application.Icon.Handle;
StrPCopy (data.szTip,Application.Title);
Shell_NotifyIcon (NIM_ADD,@data);
end;

Небольшие пояснения. Во-первых, мы создаем постое окно с дескриптором H, которое будет реагировать на сообщения иконки. После этого очищаем предопределенную структуру Data типа TNotifyIconData, затем заполняем необходимые поля. Значение поля uFlags представляют собой уведомление системы о том, что ей надо использовать. Так, использование значения NIF_ICON уведомляет систему о том, что в поле hIcon присутствует непустое значение, которое надо вывести в виде иконки; использование значения NIF_TIP говорит о наличии текста всплывающей подсказки в поле szTip; значение NIF_MESSAGE - о том, что в поле Wnd присутствует дескриптор окна, которому передается управление при возникновении того или иного сообщения у иконки.

После заполнения всех необходимых полей вызывается функция Shell_NotifyIcon со значением NIM_ADD - добавление иконки в трей.

Теперь рассмотрим реакцию иконки на сообщения:

procedure TForm1.TrayDefaultHandler (var Message:TMessage);
begin
if Message.Msg=WM_TRAYICON then
if Message.LParam=WM_LBUTTONDOWN then
begin
ShowMessage ('Left Button Down');
end;
end;

Как видно из текста, здесь в качестве реакции реализован простой вывод уведомления о нажатии левой кнопки мыши на иконке. Идентификатор WM_TRAYICON, используемый здесь, определен нами в модуле главной формы следующим образом:

такое определение необходимо для того, чтобы сообщения системы не перекрывались.

После того как мы убедились в наличии реакции и хотим закрыть приложение, нам надо удалить нашу иконку из трея, так как, если мы этого не сделаем, то она останется лежать там до следующей перегрузки Explorer'а.

procedure TForm1.FormDestroy (Sender: TObject);
begin
Shell_NotifyIcon (NIM_DELETE,@data);
end;

Здесь нам даже не потребовалось никаких вмешательств в структуру data - мы просто вызвали Shell_NotifyIcon с необходимым параметром, как показано ниже:

uses
Windows, Messages, SysUtils, Variants, Classes, Graphics,
Controls, Forms, Dialogs, StdCtrls;

const UWM_TRAYICON = WM_USER+1;
const ID_TRAYICON = 1;
type
TForm1 = class (TForm)
Button1: TButton;
procedure Button1Click (Sender: TObject);
procedure FormDestroy (Sender: TObject);
private
procedure TrayDefaultHandler (var Message:TMessage);
{Private declarations}
public
data:TNotifyIconData;
{Public declarations}
end;

procedure TForm1.TrayDefaultHandler (var Message:TMessage);
begin
if Message.Msg=UWM_TRAYICON then
if Message.LParam=WM_LBUTTONDOWN then
begin
ShowMessage ('Left Button Down');
end;
end;

procedure TForm1.Button1Click (Sender: TObject);
var H:THandle;
begin
H:=AllocateHWnd (Self.TrayDefaultHandler);
FillChar (S,SizeOf (S),#0);
data.cbSize:=SizeOf (S);
data.Wnd:=H;
data.uCallbackMessage:=UWM_TRAYICON;
data.uFlags:=NIF_ICON or NIF_TIP or NIF_MESSAGE;
data.hIcon:=Application.Icon.Handle;
StrPCopy (data.szTip,Application.Title);
Shell_NotifyIcon (NIM_ADD,@data);
end;

procedure TForm1.FormDestroy (Sender: TObject);
begin
Shell_NotifyIcon (NIM_DELETE,@data);
end;

Эта небольшая заметка лишь слегка

Вариант передачи параметра в хранимую процедуру, использующую оператор IN

В этой статье мы рассмотрим возможность передачи параметров в хранимую процедуру, использующую оператор IN. Изложение материала будет вестись на базе тестового примера, который мы будем обсуждать по ходу описания данной статьи.

Для примера, можно создать две таблицы на сервере. Первая таблица - Sellers(продавцы), вторая SoldGoods(проданные товары), которые будут связаны между собой по полю Seller.ID - SoldGoods.SellerID

С созданием и заполнением таблиц на сервере закончили. Приступим к разработке клиентской части.

Настройка компонентов: ADOConnection1.LoginPrompt := False; DataSource1.DataSet := ADOStoredProc1; DataSource2.DataSet := ADOStoredProc2; DataSource3.DataSet := ADOQuery1; Form2.DBGrid1.DataSource := DataModule1.DataSource2; Первая (главная) форма должна использовать (uses) DataModule и Form2
Вторая (форма отчёта) форма должна использовать (uses) DataModule

"Каркас" нашего приложения готов!

Самая первая задача, это соединиться с сервером из нашего приложения. Для этого нам понадобиться файл с расширением ".udl", назовём его "Connect.udl". (Создайте файл в директории с исходным кодом). При запуске этого файла должно появиться окно:

Тут мы и настраиваем соединение с сервером. Затем в обработчике события создания формы напишем код для соединения с сервером:

Как видим, в коде имеется предупреждение вида: "БУДЬТЕ ВНИМАТЕЛЬНЫ, СНАЧАЛА ДОЛЖЕН СОЗДАВАТЬСЯ DataModule1". Это означает, что в проекте перед созданием главной формы должен создаваться DataModule1. Для этого нужно нажать сочетание клавиш CTRL+SHIFT+F11 и в разделе Auto-Create Forms DataModule1 должен стоять первым. И уберите и списка Form2, эту форму будем создавать динамически.

На данный момент, мы уже имеем процедуру соединения с сервером. (Скомпилируйте и запустите проект, если нет ошибок, продолжаем далее).

Следующая задача, это получение списка продавцов с сервера и заполнения им нашего CheckListBox1, который находится на главной форме. Для этого нам нужно создать хранимую процедуру на сервере, которая будет возвращать нам список, и процедуру в клиентском приложении, которая будет в свою очередь запускать хранимую процедуру и получать данные с сервера.

Таким образом, в дальнейшем мы получим список продавцов в датасет. Приступим к заполнению CheckListBox1.

Мы в цикле заполнили Items.AddObject нашего CheckListBox1, где в первом параметре Const S мы храним имена продавцов, а в AObject храним поле ID, которое будем получать так: Integer(CheckListBox1.Items.Objects[i]);

Наш вариант передачи параметра будет работать по следующему принципу. Мы получим список продавцов с сервера из таблицы Sellers(имена и идентификаторы). Затем в клиентском приложении выберем (отметим), нужные имена продавцов, Создадим временную таблицу на сервере. В цикле заполним её идентификаторами выбранных продавцов, и будем использовать эту таблицу в запросе на выборку отчёта. Решения:

Список продавцов получен. (См. выше) Для создания, удаления временной таблицы и выбора отчёта в приложении создадим три отдельные процедуры. Первая процедура из вышеописанных будет "для создания временной таблицы".

Тем самым, вызвав эту процедуру, сервер будет создавать временную табличку под названием #TEMP.

Примечание: как мы видим, данная процедура использует параметр IN, в котором мы задаём выборку идентификаторов из таблицы #TEMP.

Совет: Так же можно использовать оператор JOIN. Например:

Итак, мы имеем процедуры на создание и удаление временной таблицы, выбора отчёта, выбора продавцов. Порядок их запуска должен быть примерно таков:

Приступим к написанию основной процедуры в обработчике события нажатия кнопки Button1, которая расположена на Form1.

Сначала мы начали транзакцию и создали временную таблицу на сервере. Затем создали цикл, который "проходит" по всем записям, хранящимся в CheckListBox1, выбирая из параметра AObject уникальный идентификатор каждого отмеченного продавца, и помещаем его в таблицу #TEMP. Далее запускаем процедуру формирования отчёта, в которой, используя, оператор IN, мы задействуем уже существующую и заполненную временную таблицу #TEMP. Выбрав отчёт, мы удаляем временную таблицу, запустив процедуру на её удаление. И последнее. Завершаем транзакцию и показываем форму отчёта.

Примечание: Наша транзакция расположена в блоке TRY : EXCEPT : END; это означает что при возникновении ошибки, она автоматически произведёт откат изменений методом RollbackTrans, и покажет MessageDlg. Иначе транзакция будет успешно завершена методом CommitTrans.

На этом мы и закончим рассмотрение нашего тестового примера.

К статье прилагается пример с описанием. Для работы примера, необходимо подключить базу (в папке DB) или создать свою, и настроить параметры соединения в файле Connect.udl(в папке Sources)

Проект, используемый в качестве примера (119 K) allGray">

Адресация пользователей в Jabber

Каждый пользователь в сети имеет уникальный идентификатор, адрес — Jabber ID (сокращённо JID). Во избежание необходимости существования сервера с полным списком всех адресов, JID подобно адресу электронной почты содержит имя пользователя (JID node) и DNS-адрес сервера (JID domain), на котором зарегистрирован пользователь, разделённые знаком (@). Например, пользователь user, зарегистрированный на сервере example.com, будет иметь следующий адрес (JID): user@example.com.

Также пользователь может подключаться, находясь в разных местах, сервер позволяет определять дополнительное значение, называемое ресурсом, который идентифицирует клиента пользователя в данный момент. Так можно включить в адрес пользователя (JID) имя его ресурса (JID resource), добавив через слэш в конце адреса.

К примеру, пусть полный адрес пользователя будет user@example.com/work, тогда сообщения, посланные на адрес user@example.com, дойдут на указанный адрес вне зависимости от имени ресурса, но сообщения для user@example.com/work дойдут на указанный адрес только при соответствующем подключённом ресурсе.

Адреса (JID) могут также использоваться без явного указания имени пользователя (с указанием имени ресурса или без такового) для системных сообщений и для контроля специальных возможностей на сервере.

Запомним эту информацию, она нам пригодятся в дальнейшем.

Атрибуты элементов XML

При приходе XML у тегов могут быть следующие основные атрибуты:

Id — уникальный идентификатор, так называемый атрибут 'системы обнаружения атак'. Позволяет конкретно идентифицировать полученные данные. Рекомендовано делать его случайным. Но в принципе это не обязательно.

Теги могут включать также и дополнительные атрибуты, зависящие от передоваемых данных.

Пример строфы <PRESENCE> с некоторыми атрибутами Вы можете увидеть ниже:

Базовые семантические модули

После того как мы прошли авторизацию, разберем основные базовые семантические модули XML-строф реализованных в протоколе, их довольно немного:

<Presence> — презентационные данные, определяют статусное состояние, видимость пользователей и управление подпиской.

<Message> — собственно сами сообщения переданные или принятые пользователем.

<IQ> — Info Query, данные информационных запросов, включают в себя сами запросы, а также результаты выполнения. Данные запросы позволяют Jabber-клиентам обменивается различными данными между собой. Информационное наполнение запроса и ответа определено в пространстве имен дочернего элемента. Дополнительные расширения протокола (XEP — XMPP Extension Protocol) очень сильно используют <iq> запросы. Подробнее об них я расскажу далее.

Дочерние элементы

У XML-строфы <Message> могут быть следующие дочерние элементы, определенные пространством имен 'jabber:client' или 'jabber:server'. По умолчанию за этими элементами зарезервировано пространство имен 'jabber:client'. Если <Message> имеет тип error то обработка такого сообщения идет в соответствии с RFC 3920 XMPP-Core.

Элемент строфы <Message> может содержать любой из следующих дочерних элементов без явного объявления пространства имен:

Где элемент <body> — является телом сообщения. В значении элемента содержится сам текст сообщения, предварительно перекодированный из-за ограничений XML. Элемент может содержать атрибут 'xml:lang' содержащий язык сообщения. В <Message> могут быть включены множественные экземпляры элементов <Body>, но только при условии, что каждый экземпляр обладает атрибутом 'xml:lang' с отличным языковым значением.

Элемент <Subject> определяет тему сообщения. На него действуют те-же правила, что и для <Body>. Множественные экземпляры <Body> могут быть включены для расширения и дополнения смежных тем, но при условии, что каждый экземпляр обладает атрибутом 'xml:lang' с отличным языковым значением.

Элемент <thread> cлужит для обеспечения хронологии сеанса. Значение <thread> элемента сгенерированного отправителем должно быть послано назад в любых ответах. Этот элемент является дополнительным и обычно не используется для обмена сообщениями между пользователями. Используется он в сеансах связи. Более подробно можно прочитать о нем в RFC 3921.

Дочерние элементы

XML-строфа <Presence> может содержать следующие дочерние элементы, определенные пространством имен 'jabber:client' или 'jabber:server': <show>, <status>, <priority>. По умолчанию за этими элементами зарезервировано пространство имен 'jabber:client'. Если <Message> имеет тип error то обработка такого сообщения идет в соответствии с RFC 3920 XMPP-Core.

Элемент <show> определяет статус контакта и может иметь следующие значения:

Пустой элемент <show/> определяет статус контакта " В сети ".

Элемент <status> определяет статусное сообщение. Значением элемента является строка с текстом сообщения, например:

Необязательный элемент <priority> определяет приоритет уровня ресурса. Значением элемента является число от -128 до 127.

Информационные запросы <IQ>

Информационные запросы <IQ> разделяются на стандартные, определенные пространством имен 'jabber:client' или 'jabber:server', обеспечивающие базовые функциональные возможности и расширенные.

Расширенные запросы, определенные дополнительными пространствами имен, описаны в различных дополнениях к протоколу XMPP.

Пространство имен расширенных запросов, может содержать любое значение, кроме зарезервированных следующих пространств имен: "jabber:client", "jabber:server" или "http://etherx.jabber.org/streams". Такое расширение позволяет придать протоколу XMPP дополнительную функциональность и гибкость. Таким образом, расширенный информационный запрос <IQ> может содержать один или более дополнительных дочерних элементов, определяющих информационное наполнение, которое расширяет значение данного запроса. Это кардинальное отличие от стандартного информационного запроса.

Стандартный запрос не может содержать, дочерние элементы, кроме элемента <error>. Наличие данного элемента в запросе показывает наличие ошибки.

Поддержка любого расширенного пространства имен является дополнительной возможностью со стороны клиента. Если клиент не понимает такое пространство имен, то есть фактически не поддерживает данное расширение, то он должен проигнорировать данный пакет. Более подробно вы можете прочитать об этом в RFC 3921.

Структурная схема обмена информационными запросами:

Как мы видим, на структурной схеме обмен между клиентами происходит по такому алгоритму. Запрашивающая сторона посылает <IQ> запрос с атрибутом type равным значению "get". Данный атрибут на принимающей стороне говорит клиенту, что вы должны предоставить информацию по данному запросу (для расширенных запросов при условии, что он поддерживается клиентом). Принимающая сторона отправляет ответ с атрибутом с атрибутом type равным значению "result".

Это первый вариант обмена. Существует и второй, когда запрашивающая сторона информирует принимающую о каком-то изменении, для этого она отправляет запрос с атрибутом type равным значению "set". Данное значение атрибута говорит о том, что принимающая сторона должна обработать присланные данные. Если принимающая сторона не может по каким-либо причинам обработать присланные данные, то в ответ она посылает строфу <IQ> с атрибутом type равным значению "error" информируя запрашивающую сторону о невозможности обработки. Если принимающая сторона корректно обработала запрос c атрибутом "set" то она возвращает ответ с атрибутом равным значению "result".

Пример расширенного запроса определяющий информацию об использованном клиенте (XEP-0092 Software Version):

Основные сведения о протоколе XMPP

В основе протокола XMPP (eXtensible Messaging and Presence Protocol) лежит язык XML. XMPP является открытым, свободным протоколом для мгновенного обмена сообщениями и информацией о присутствии в режиме околореального времени.

Изначально спроектированный легко расширяемым протокол помимо передачи текстовых сообщений поддерживает передачу голоса и файлов по сети.

Протокол регламентируется следующими стандартами:

RFC 3921 — Extensible Messaging and Presence Protocol (XMPP): Instant Messaging and Presence

Следует также отметить, так как протокол является текстовым, а не бинарным соответственно у этого протокола есть слабые стороны, а именно: избыточность передаваемой информации, отсутствие возможности передачи двоичных данных приводит к использованию различных способов перекодировки. В результате этого, для передачи файлов приходится использовать дополнительные протоколы, например HTTP. Если этого не избежать, то XMPP обеспечивает встроенную передачу файлов кодируя информацию используя base64. Другая двоичная информация, такая как закодированный разговор или графические иконки включаются с использованием такого же метода. Однако прежде чем двигаться дальше рассмотрим адресацию пользователей с Jabber-сетях.

Отправка и прием сообщений <Message>

Прием и отправка сообщений осуществляется через XML-строфу <MESSAGE>. Так как в Jabber-е предусмотрены разные типы сообщений, то для их разграничений предусмотрен атрибут type содержащий информацию о типе сообщения.

chat — Одиночное сообщение от клиента к клиенту.

error — Сообщение об ошибке. Произошедшая ошибка связанна с предыдущим, посланным одиночным сообщением.

groupchat — Групповой чат. Данное сообщение пришло с группового чата, действующего по признаку "Одно сообщение — многим получателям".

headline — Системное сообщение, автоматически генерируется различными сервисами для шировещательной рассылки (новости, спорт, RSS-каналы и пр.) Отвечать на такие сообщение не нужно, да и не зачем.

normal — одиночное сообщение, посылаемое вне контекста взаимно-однозначного сеанса связи или группового чата. То есть это такое сообщение, на которое пользователь может дать ответ, не учитывая хронологии сеанса связи.

Перекодировка символов текста

Поскольку символы "<" и ">" используются для обозначения самих XML тегов, то их вставка в текст сообщения недопустима (за исключением случая, когда вставлен символ ">", но никакой тег не был открыт). Поэтому для корректного формирования XML следующие символы должны быть заменены в теле сообщения при отправке оного и соответственно обратно возвращены при приеме:

Таким образом, чтобы написать "2>1", нужно написать "2>1". То же самое касается и знака "&" — он заменяется "&". Также рекомендуется заменять и кавычки (хотя в большинстве случаев они хорошо распознаются и без этого). Эквивалент двойных кавычек — """

Подготовка

Сразу оговорюсь, что я не ставлю перед собой задачу написать полноценно работающий клиент соответствующий полному стандарту XMPP. Слишком большой труд, скажем так, однако основные методы работы с XMPP будут включены в мой исходный компонент.

В качестве основы для работы клиента мной были взяты наработки по работе с WinSock , используемые им в TICQClient, немного портированные, кое-где измененные и дополнительно комментированные мной, для нашего демо-клиента.

В качестве парсера XML мной был взят TjanXMLParser2, благо он бесплатный, довольно быстрый. Стандартный парсер MSXML был мной отброшен по причине, того, что некоторые XML-пакеты приходили синтаксически неправильные, что начисто отрубало желание этого парсера работать с ними.

Что касается приведенных далее листингов обмена протоколом, я постарался описать самые интересные части, если у вас кое-где возникнут вопросы, подробнее вы можете узнать в RFC. Все 800 основного RFC страниц я не смогу Вам подробно изложить, но критические места постараюсь.

Также сразу оговорюсь, что наш пример не будет поддерживать шифрование, то есть данные будут передаваться в открытом виде. Сделано это для упрощения понимания примера. Вышло, то, что вышло, а хорошо иль плохо получилось судить Вам, уважаемые коллеги.

Итак, для тестирования нашего примера, мной был зарегистрирован на сайте jabber.ru аккаунт delphi-test@jabber.ru с паролем delphi-test. Эти данные нам понадобятся для разбора протокола обмена между сервером jabber (далее — Сервер) и нашим клиентом (также — Клиент) далее.

Прохождение аутенфикации

Итак, первым действием при соединении с сервером Jabber, которым должен выполнить наш клиент — является аутенфикация. Аутенфикация будет происходить используя механизм SASL аутенфикации, описанный в в "RFC 2831 — Using Digest Authentication as a SASL Mechanism", алгоритм работы который будет рассмотрен подробнее, чуть далее.

Итак, мы установили физическое соединение с сервером, теперь нам нужно пройти аутенфикацию, для этого клиент посылает серверу следующий пакет:

В ответ сервер пришлет подтверждение, о рукопожатии:

Сразу же после приема первого пакета, придет пакет, содержащий информацию о возможностях и доступных механизмах сервера. Данные возможности нужны, будут для полноценной работы с сервером:

Что мы видим в пакете, видим, что сервер поддерживает zip компрессию при передаче пакетов, поддерживает механизм аутенфикации DIGEST-MD5, и другие возможности. Стоит также отметить, что возможности сервера зависят от самого сервера и в зависимости от программы могут изменяться. Подробнее вы можете узнать в RFC 3920. Однако нас интересует то, что сервер поддерживает механизм аутенфикации DIGEST-MD5. Отлично, скажем мы и отправим ему пакет, говорящий о том, что мы хотим пройти аутенфикацию используя механизм DIGEST-MD5.

После получения данного пакета сервер присылает нам, так называемый challenge-пакет:

Данный пакет мы должны будем разобрать. Как это сделать? Ранее внимательный читатель обратил внимание, что некоторые пакеты могут передаваться в кодировке Base64. Это наш случай. Текстовый элемент содержит информацию в данной кодировке, которая после раскодирования примет следующий вид:

Из этой строки нам понадобится значение Nonce для последующего построения ответа серверу, после чего мы подготавливаем строку ответа, которую мы передадим на сервер в ответном пакете, предварительно закодировав ее в Base64. Итак, ответная строка будет иметь следующий вид:

nonce — Уникальный код сессии, присланный нам ранее сервером

cnonce — Уникальный код ответной клиентской сессии, сгенерированный клиентом

nc — Так называемый once count — сколько раз был использован текущий nonce. Обычно значение параметра равно 00000001, его и будем использовать. На самом деле параметр довольно интересный и стоит отдельного рассмотрения и изучения в RFC, но как показала практика его смело можно игнорировать.

digest-uri — Протокол подключения, для XMPP сервера он состоит из соединения строк "xmpp/" + JID Domain

charset — поддержка кодировки пароля и имени, в нашем случае UTF-8

И самый важный параметр response в котором заключен ключ ответа серверу, включающий в себя пароль и ответные данные в формате MD5 строящийся по определенному алгоритму.

Алгоритм построения строки ответа и параметра Response более подробно мы рассмотрим далее в подразделе "RFC 2831 использование MD5-Digest аутенфикации в SASL". Пока примем к сведению, что текущее и следующие два действие относится уже к данному алгоритму.

Итак, строку ответа, мы сформировали, закодировали в Base64 и отправляем обратно серверу (всё это должно быть в одну строчку, но, чтобы страница не расползалась, разбито на несколько):

Если все нормально мы получим следующий ответ:

Тут нам особо ничего не нужно, подтверждаем принятие его, отправив со стороны клиента:

И если все прошло успешно, то получаем со стороны сервера пакет, говорящий нам о том, что аутенфикация прошла успешно:

После чего по стандарту мы должны связать нашего клиента с JID-ресурсом, что мы и делаем, посылая строку в формате UTF-8:

Примечание: Все листинги будут представлены в ASCII формате, хотя на самом деле прием и посылка пакетов ведется в UTF-8. Однако что бы Вам не читать крякозаблы в листингах примеров, кодировка будет в показана в ASCII.

Сервер подтверждает связывание ресурса с данным клиентом:

и все, аутенфикация пройдена, значок клиента в контакт-листе становится зелененьким, теперь он может посылать и принимать сообщения.

Пространства имен XML

Так как первоначально XMPP был задуман, как протокол, поддерживающий расширения, перед разработчиками встал вопрос, как можно реализовать данные расширения, не внося коррективы в основной протокол. И решение нашлось. Это решение — пространство имен, довольно известное в XML.

Пространство имён в XML — именованная совокупность имён элементов и атрибутов, служащая для обеспечения их уникальности в XML-документе. Все имена элементов в пределах пространства имён должны быть уникальны. Таким образом, реализуется различение одинаковых элементов XML или атрибутов. Для клиентов Jabber зарезервировано пространство имен "jabber:client"

Пространства имён объявляются с помощью зарезервированного XML атрибута xmlns, значение которого является названием пространства имен.

Например, элемент <QUERY> описанный пространством имен 'jabber:iq:roster' выглядит так:

Работа с ростер-листом (списком контактов)

Ростер-лист или аналог списка контактов в сетях ICQ в Jabber-е представлен списком, содержащим JID-контакты в виде элементов XML хранящимся на сервере от имени пользователя. Так как ростер-лист сохранен сервером от имени пользователя, то пользователь может обратиться к информации списка от любого ресурса.

Управление ростер-листом (списком) осуществляется через расширенный информационный запрос <IQ> содержащий дочерний элемент <query> c пространством имен 'jabber:iq:roster'. Элемент <query> может содержать один или более дочерних элементов <ITEM> содержащих информацию о контакте.

Уникальный идентификатор каждого элемента списка <item> — это JID контанта, формируемый в атрибуте jid Значение атрибута jid имеет форму user@domain без указания ресурса. Текущее состояние подписки пользователя (контакта) относительно элемента <item> зафиксировано в атрибуте subscription и может принимать следующие значения:

none — У пользователя нет подписки к контакту, нет подписки и к информации присутствия пользователя

to — у пользователя есть подписка к информации присутствия контакта, но у контакта нет подписки к информации присутствия пользователя

from — у контакта есть подписка к информации присутствия пользователя, но у пользователя нет подписки к информации присутствия контакта

both — у пользователя есть подписка к присутствию контакта, да и у контакта есть подписка к пользователю.

RFC 2831 использование MD5-Digest аутенфикации в SASL

Итак, аутенфикация решает следующие задачи: Передача пароля на сервер, в закрытом виде, защиту от повторяющихся атак (monitoring nc value), защиту (monitoring nonce) в определённый промежуток времени от определённого клиента. Для того, что бы понять, как работает данный стандарт, разберем основы SASL.

Метод SASL (Simple Authentication and Security Layer) используется для добавления поддержки аутентификации в различные протоколы соединения. Для аутентификации могут быть использованы различные механизмы.

Имя требуемого механизма задаётся клиентом в команде аутентификации. Если сервер поддерживает указанный механизм, он посылает клиенту последовательность окликов (challenges), на которые клиент посылает ответы (responses), чтобы удостоверить себя. Содержимое окликов и ответов определяется используемым механизмом и может представлять собой двоичные последовательности произвольной длины. Кодировка последовательностей определяется прикладным протоколом. Вместо очередного оклика сервер может послать подтверждение аутентификации или отказ. Кодировка также определяется протоколом. Вместо ответа клиент может послать отказ от аутентификации. Кодировка опять определяется протоколом. В результате обменов откликам и ответами должна произойти аутентификация (или отказ), передача идентификатора клиента (пустой идентификатор влечёт получение идентификатора из аутентификации) серверу и, возможно, договорённость об использовании безопасного транспортного протокола (security layer), включая максимальный размер буфера шифрования.

Идентификатор клиента может отличаться от идентификатора, определяемого из аутентификации, для обеспечения возможности работы прокси.

Схема работы SASL для нашего клиента основана на использовании механизма MD-Digest и имеет следующий алгоритм работы:

Сервер посылает случайную строку nonce, наличие поддержки utf-8 в параметре charset для имени и пароля, алгоритм аутентификации (обязательно md5-sess) в параметре algorithm.

То есть те данные, что мы раскодировали ранее из пакета challenge:

Клиент отвечает строкой, содержащей: идентификатор клиента username, идентификатор домена realm, полученную от сервера случайную строку nonce, случайную строку клиента cnonce, номер запроса (позволяет серверу заметить попытку replay attack) nc. параметр digest-uri (сочетание имени сервиса, имени сервера т.е. 'xmpp/' + JID Domain), строку responce подтверждающею знание пароля и ответ на оклик (MD5 от имени пользователя, realm, пароля, случайной строки сервера, случайной строки клиента, идентификатора клиента, номера запроса, уровня защиты, digest-uri; некоторые компоненты берутся в виде MD5, некоторые в исходном виде, некоторые в обоих видах), использование utf-8 для имени и пароля, принятый алгоритм шифрования и идентификатор клиента.

То есть, как вы догадались эта та строка, которую мы формируем в ответ:

Сервер проверяет ответ на оклик и посылает ответ на ответ в похожем формате (но всё же отличающемся, чтобы клиент мог убедиться в подлинности сервера). Данный механизм слабее системы с открытыми ключами, но лучше простой CRAM-MD5.

Примечание: Стоит отметить, что может предусматриваться упрощённый протокол повторной аутентификации (начинается сразу с посылки клиентом ответа с увеличенным на 1 номером запроса).

Алгоритм вычисления строки ответа response имеет следующую формулу:

Выражение { a, b, ... } — означает сложение строк a, b

HEX(n) — 16-байтовый MD5-хеш n, приведенный в 32 байтовую Hex-строку в нижнем регистре. Фактически строковое представление дайджеста MD5.

H({k, ":", s}) — 16-байтовый MD5-хеш, полученный в результате сложения строки k, ":", S

Как видите, особо ничего сложного нет. Вот алгоритм расчета реализованный мной на Delphi:

На входе функция получает параметры рассмотренные нами ранее.

Статусы, состояния, информация о присутствии, управление подпиской <Presence>

Прием и отправка статусных сообщений, а также информации о видимости контактов и подписки на сообщения от них, осуществляется через XML-строфу <Presence>.

Атрибут type строфы <Presence> является дополнительным.

Строфа, которая не обладает атрибутом type, используется Jabber-ом, для сообщений о присутствии контакта в сети Jabber и указывает на то, что данный контакт находится в сети (онлайне) и доступен для коммуникации.

Если атрибут type присутствет в строфе <Presence>, то он управляет подпиской на сообщения и смену статусов другого контакта (объекта). Аналог подписки в IM-сетях является прохождение авторизации в ICQ.

Если атрибут включен, то он должен содержать иметь одно из следующих значений:,

unavailable — Сигнализирует, что данный контакт, больше не доступен для коммуникаций. Фактически контакт вышел в оффлайн.

subscribe — Запрос на подписку (авторизацию) от другого контакта.

subscribed — Информирует о том, что контакт разрешил авторизацию.

unsubscribed — Запрос на аннулирование подписки (отозвание авторизации) от другого контакта.

probe — Запрос о текущем присутствии контакта только сервером от имени пользователя.

error — Ошибка, произошедшая при доставки предыдущих данных. Обработка такого сообщения идет в соответствии с RFC 3920 XMPP-Core.

Например, запрос на подписку от контакта ivanov@jabber.ru для нашего контакта может выглядеть так:

Структура XML-пакетов Jabber протокола (XML Streams)

Структура XML пакетов получаемых с сервера и передаваемых на него по спецификации RFC 3920 имеет следующий вид:

Как вы видите, на схеме представлена иерархическая структура XML подразделенная на следующие элементы, так называемый поток XML и элементы строф XML.

Поток XML — является контейнером для хранения элементов строф XML. Поток XML начинается с открытия тэга <STREAM> (с соответствующими атрибутами и пространством имен), конец потока XML заканчивается закрытием тега </STREAM>. Во время обмена с сервером, клиент и сам сервер может посылать неограниченное количество элементов строф в потоке XML.

Строфы XML — это дискретные семантические модули представленные элементами, заключенными в потоке XML. Строфы XML являются дочерними элементами (child node) корня XML <STREAM>. Начало любой строфы XML обозначено началом элемента (например, <PRESENCE>), конец строфы XML обозначен завершающим тегом (</PRESENCE>). В примере строфы XML: <PRESENCE>, <MESSAGE>, <IQ>. Каждая строфа XML представляет собой конкретную информацию, так например строфа <MESSAGE> представляет сообщение, а <IQ> информационный запрос. Более подробно строфы будут рассмотрены далее.

Примечание: несмотря на стандарт, мной было замечено, что с некоторых серверов могут приходить пакеты, просто содержащие строфы XML, но включенные в поток XML.

Управление ростер-листом

Добавление или редактирование контакта. При отсутствии контакта в ростер-листе контакт будет добавлен, при наличии отредактирован.

Добавление / корректировка. Клиент посылает следующий пакет.

После добавления/обновления информации о контакте на сервере, сервер оповещает все доступные ресурсы пользователя о внесенной информации. Оповещение служит сигналом для синхронизации данных клиентов о данном контакте с данными сервера.

В любое время, пользователь удалить контакт из ростер-списка, для этого клиент должен послать запрос с атрибутом subscription элемента <item> равным значению 'remove':

Как и в случае с добавлением/корректировкой контакта сервер оповещает клиенты о удалении контакта. Указанием факта удаления служит атрибут subscription равным значению 'remove' в элементе <item>.

система для быстрого обмена сообщениями

Как вы видите, ничего особо

Запрос списка контактов при входе в систему

При входе в систему клиент Jabber должен послать серверу информационный запрос о получении ростер-листа.