From 8d05f80cecfcc4eba78e041aaba8f6ff482864da Mon Sep 17 00:00:00 2001 From: Richard Lewis Date: Tue, 27 Mar 2018 10:00:41 +0100 Subject: [PATCH] Sticker messages (m.sticker) (#1158) --- changelogs/client_server.rst | 8 +++ event-schemas/examples/m.sticker | 25 +++++++++ .../msgtype_infos/image_info.yaml | 8 ++- .../msgtype_infos/thumbnail_info.yaml | 8 ++- event-schemas/schema/m.sticker | 34 ++++++++++++ specification/modules/stickers.rst | 53 +++++++++++++++++++ specification/targets.yaml | 1 + 7 files changed, 133 insertions(+), 4 deletions(-) create mode 100644 event-schemas/examples/m.sticker create mode 100644 event-schemas/schema/m.sticker create mode 100644 specification/modules/stickers.rst diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index 34fbfdbea37..c29f38c76fd 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -10,8 +10,16 @@ Unreleased changes - ``GET /rooms/{roomId}/event/{eventId}`` (`#1110 `_). + - Sticker messages: + - Add sticker message event definition. + (`#1158 `_). + - Spec clarifications: + - Update ``ImageInfo`` and ``ThumbnailInfo`` dimension schema descriptions + to clarify that they relate to intended display size, as opposed to the + intrinsic size of the image file. + (`#1158 `_). - Mark ``home_server`` return field for ``/login`` and ``/register`` endpoints as deprecated (`#1097 `_). diff --git a/event-schemas/examples/m.sticker b/event-schemas/examples/m.sticker new file mode 100644 index 00000000000..f00e5b238e5 --- /dev/null +++ b/event-schemas/examples/m.sticker @@ -0,0 +1,25 @@ +{ + "age": 242352, + "content": { + "body": "Landing", + "info": { + "mimetype": "image/png", + "thumbnail_info": { + "mimetype": "image/png", + "h": 200, + "w": 140, + "size": 73602 + }, + "h": 200, + "thumbnail_url": "mxc://matrix.org/sHhqkFCvSkFwtmvtETOtKnLP", + "w": 140, + "size": 73602 + }, + "url": "mxc://matrix.org/sHhqkFCvSkFwtmvtETOtKnLP" + }, + "origin_server_ts": 1431961217939, + "event_id": "$WLGTSEFSEF:localhost", + "type": "m.sticker", + "room_id": "!Cuyf34gef24t:localhost", + "sender": "@example:localhost" +} diff --git a/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml b/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml index b4eab413a2c..4d2a9964636 100644 --- a/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml +++ b/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml @@ -2,10 +2,14 @@ $schema: http://json-schema.org/draft-04/schema# description: Metadata about an image. properties: h: - description: The height of the image in pixels. + description: |- + The intended display height of the image in pixels. This may + differ from the intrinsic dimensions of the image file. type: integer w: - description: The width of the image in pixels. + description: |- + The intended display width of the image in pixels. This may + differ from the intrinsic dimensions of the image file. type: integer mimetype: description: The mimetype of the image, e.g. ``image/jpeg``. diff --git a/event-schemas/schema/core-event-schema/msgtype_infos/thumbnail_info.yaml b/event-schemas/schema/core-event-schema/msgtype_infos/thumbnail_info.yaml index 5a233b241a3..82ffaf5e460 100644 --- a/event-schemas/schema/core-event-schema/msgtype_infos/thumbnail_info.yaml +++ b/event-schemas/schema/core-event-schema/msgtype_infos/thumbnail_info.yaml @@ -2,10 +2,14 @@ $schema: http://json-schema.org/draft-04/schema# description: Metadata about a thumbnail image. properties: h: - description: The height of the image in pixels. + description: |- + The intended display height of the image in pixels. This may + differ from the intrinsic dimensions of the image file. type: integer w: - description: The width of the image in pixels. + description: |- + The intended display width of the image in pixels. This may + differ from the intrinsic dimensions of the image file. type: integer mimetype: description: The mimetype of the image, e.g. ``image/jpeg``. diff --git a/event-schemas/schema/m.sticker b/event-schemas/schema/m.sticker new file mode 100644 index 00000000000..1dd1173c9c2 --- /dev/null +++ b/event-schemas/schema/m.sticker @@ -0,0 +1,34 @@ +--- +allOf: + - $ref: core-event-schema/room_event.yaml +description: This message represents a single sticker image. +properties: + content: + properties: + body: + description: |- + A textual representation or associated description of the sticker + image. This could be the alt text of the original image, or a message + to accompany and further describe the sticker. + type: string + info: + allOf: + - $ref: core-event-schema/msgtype_infos/image_info.yaml + description: |- + Metadata about the image referred to in ``url`` including a thumbnail + representation. + url: + description: |- + The URL to the sticker image. This must be a valid ``mxc://`` URI. + type: string + required: + - body + - info + - url + type: object + type: + enum: + - m.sticker + type: string +title: StickerMessage +type: object diff --git a/specification/modules/stickers.rst b/specification/modules/stickers.rst new file mode 100644 index 00000000000..346b0d84fe9 --- /dev/null +++ b/specification/modules/stickers.rst @@ -0,0 +1,53 @@ +.. Copyright 2018 New Vector Ltd. +.. +.. Licensed under the Apache License, Version 2.0 (the "License"); +.. you may not use this file except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. + +Sticker Messages +================ + +.. _module:stickers: + +This module allows users to send sticker messages in to rooms or direct +messaging sessions. + +Sticker messages are specialised image messages that are displayed without +controls (e.g. no "download" link, or light-box view on click, as would be +displayed for for `m.image`_ events). + +Sticker messages are intended to provide simple "reaction" events in the message +timeline. The matrix client should provide some mechanism to display the sticker +"body" e.g. as a tooltip on hover, or in a modal when the sticker image is +clicked. + +Events +------ +Sticker events are received as a single ``m.sticker`` event in the +``timeline`` section of a room, in a ``/sync``. + +{{m_sticker_event}} + +Client behaviour +---------------- + +Clients supporting this message type should display the image content from the +event URL directly in the timeline. + +A thumbnail image should be provided in the ``info`` object. This is +largely intended as a fallback for clients that do not fully support the +``m.sticker`` event type. In most cases it is fine to set the thumbnail URL to the +same URL as the main event content. + +It is recommended that sticker image content should be 512x512 pixels in size +or smaller. The dimensions of the image file should be twice the intended +display size specified in the ``info`` object in order to assist +rendering sharp images on higher DPI screens. diff --git a/specification/targets.yaml b/specification/targets.yaml index 122904e9886..50a9fb8d5b1 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -62,6 +62,7 @@ groups: # reusable blobs of files when prefixed with 'group:' - modules/cas_login.rst - modules/dm.rst - modules/ignore_users.rst + - modules/stickers.rst title_styles: ["=", "-", "~", "+", "^", "`", "@", ":"]